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Notices 


Any reference to an IBM licensed program in this publication is not intended to 
state or imply that only IBM’s program or other product may be used. Any func- 
tionally equivalent product, program, or service that does not infringe any of IBM’s 
intellectual property rights may be used instead of the IBM product, program, or 
service. Evaluation and verification of operation in conjunction with other products, 
except those expressly designated by IBM, is the user's responsibility. 


IBM may have patents or pending patent applications covering subject matter in 
this document. The furnishing of this document does not give you any license to 
these patents. You can send license inquiries, in writing, to the IBM Director of 
Licensing, IBM Corporation, 500 Columbus Avenue, Thornwood, NY 10594, USA. 


Licensees of this program who wish to have information about it for the purpose of 
enabling: (i) the exchange of information between independent created programs 
and other programs (including this one) and (ii) the mutual use of the information 
which has been exchanged, should contact IBM Canada Ltd., Department 071, 
1150 Eglinton Avenue East, North York, Ontario M38C 1H7, Canada. Such informa- 
tion may be available, subject to appropriate terms and conditions, including in 
some cases payment of a fee. 


This publication contains examples of data and reports used in daily business oper- 
ations. To illustrate them as completely as possible, the examples include the 
names of individuals, companies, brands, and products. All of these names are ficti- 
tious and any similarity to the names and addresses used by an actual business 
enterprise is entirely coincidental. 


Programming Interface Information 


This book is intended to help you write Integrated Language Environment (ILE) 
C/400 programs using the ILE C/400 compiler or ILE C++ programs using the 
Visual Age for C++ for AS/400 compiler. It primarily documents general-use pro- 
gramming interfaces and associated guidance information provided by the com- 
pilers. 


Trademarks and Service Marks 


The following terms are trademarks of the International Business Machines Corpo- 
ration in the United States or other countries or both: 


AS/400 Application System/400 
OS/400 C/400 

400 PROFS 

Integrated Language Environment IBM 

IBMLink 


Microsoft and Windows are trademarks or registered trademarks of Microsoft Cor- 
poration. 


Other company, product, and service names, which may be denoted by a double 
asterisk (**), may be trademarks or service marks of others. 
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About This Book 


This book contains reference information on Machine Interface (Ml) instructions. 


Use this book as a reference when you write Integrated Language Environment 
(ILE) C and C++ applications. This book is intended to be used in conjunction with 
the Machine Interface Functional Reference, SC41-4810. 


This book does not describe how to program in the C programming language, nor 
does it explain the concepts of ILE. 


For information about other AS/400 publications, see either of the following: 


e The Publications Reference book, SC41-4003, in the AS/400 Softcopy Library. 

¢ The AS/400 Information Directory, a unique, multimedia interface to a 
searchable database containing descriptions of titles available from IBM or from 
selected other publishers. The AS/400 Information Directory is shipped with 
your system at no charge. 


For a list of related publications, see “Bibliography” on page 273. 


Who Should Use This Book 


This book is intended for programmers who are familiar with the ILE C/400 pro- 
gramming language and who plan to use the MI function interface in their ILE C or 
C++ applications. You also need knowledge of ILE as explained in /LE Concepts, 
SC41-4606 


A Note About Examples 
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The examples in this book are written in a simple style. These examples do not 
demonstrate all of the possible uses of C language constructs. Some examples 
are only code fragments and do not compile without additional code. 


For ILE C users, all complete runnable examples for the machine interface 
instructions can be found in library QCLE, in source file QACSRC. The example 
names are the same as the function name or instruction name. For example, the 
source code for the example illustrating the use of the cpybla function in this book, 
can be found in library QCLE, file QACSRC, member CPYBLA. 


The QSYSINC library must be installed. 
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This book describes a set of Machine Interface (MI) library functions that provide 
system-level programming capabilities. The syntax, parameter descriptions, notes 
on usage, return values and exceptions are presented where applicable for each 
function. The information presented here is intended to provide you with an indi- 
cation of what each function can do and highlight any differences in behavior 
between the function and the MI instruction. You will need to refer to the Machine 
Interface Functional Reference, SC41-4810 for a complete description of each MI 
instruction. 


The Machine Interface (Ml) is the machine instruction set that allows you to 
access low level machine procedures. 


Most of the MI instructions can be accessed through two interfaces: the builtin inter- 
face and the function interface. Some of the functions in the MI library do not have 
a builtin interface, and some of the builtins do not have a function interface. 


The builtin interface is a builtin routine that directly accesses the low level machine 
procedure. You cannot take the address of a routine through its builtin interface, 
and there is no stack frame associated with a call to a routine through its builtin 
interface. Performance may be improved if you use the builtin interface but the 
machine procedures do not use a consistent parameter passing mechanism nor do 
they make use of return values and null terminated strings like C library functions 
do. 


Although builtin versions are mentioned in the discussion of the function, the syntax 
is not provided. You will need to refer to the Machine Interface Functional Refer- 
ence where the syntax of all the MI builtins are provided. 


The function interface provides an easier, more consistent way for passing param- 
eters and using the function calling conventions. If the parameter lists of the func- 
tion interface and the builtin interface to a machine procedure are identical, the 
function interface is available as a macro that maps directly to the builtin. Ifa 
parameter for an MI function is a string which specifies the name of an AS/400 
object, the string must not have any preceding blanks. 


See Table 1 on page 255 for a summary of all the ILE C/C++ MI function proto- 
types. For each function, the prototype for the associated builtin is also provided if 
it is identical to that of the function. The table also contains the prototypes for 
builtins which do not have a function interface. 


The MI header files allow you to access declarations for both the builtin and func- 
tion interface to an MI instruction. 


Not all the MI instructions described in the Machine Interface Functional Reference 
can be accessed through the functions declared in the MI header files. Many MI 
instructions are simply not accessible in ILE since the operation they perform can 
be done just as easily using standard C language constructs. For some of these 
instructions an equivalent C function is supplied to perform the same operation as 
the MI instruction. These cases are noted in the function description. 


Access to the Machine Interface 


You use the AS/400 pointer types with the type definitions and function declarations 
that make up the MI library to access the MI. The header file <pointer.h> contains 
the type definitions (typedefs) of the AS/400 pointer types. 


Examples 
This example shows you how to use the MI builtin MATS to materialize the attri- 
butes of a user space object. 


#include <pointer.h> 

#include <QSYSINC/MIH/RSLVSP> 
#include <QSYSINC/MIH/MATS> 
#include <QSYSINC/H/QUSCRTUS> 


#define CREATION SIZE 65536 
int main(void) 


{ 
_SPC_Template_T space_t; 
_SYSPTR ptr_to_space; 
int error_code = 0; 


QUSCRTUS ("MYSPACE QTEMP ae 
"MYSPACE ", 
CREATION SIZE, 
"\o" ; 
"SALL " : 
"MYSPACE example for Programmer's Reference 15 
"YES " : 
&error_code); 


ptr_to space = rslvsp(_Usrspc, "MYSPACE", "QTEMP", _AUTH_OBJ_ MGMT) ; 
space t.TmpSize = sizeof(_SPC Template T); 


_MATS(&space_t, &ptr_to_ space); 
} 


In this example, the space is created using the Create User Space (QUSCRTUS) 
API. On the call to MATS, the argument space_t contains the address of the 
structure into which the space attributes are materialized. This structure is defined 
in the <QSYSINC/MIH/MATS> header file. The argument pir_to_space contains 
the address of the system pointer to the space object whose attributes are material- 
ized. This pointer was obtained by using the rslvsp function to resolve to the 
space object. The type definition for SYSPTR is included in the <pointer.h> 
header file. 


Omitted Operands 
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If you want to omit an operand (referred to as a "null operand" in the Machine Inter- 
face Functional Reference) when you use the function interface to access the MI, 
you must supply a NULL pointer. This only applies to omitted pointer operands. 
This allows you to use a single interface to access all variations of an MI instruc- 
tion. 


Examples 

This example shows how the process control space pointer (the second parameter) 
may be omitted from the matpratr (Materialize Process Attributes) function interface 
by passing a NULL pointer on the call to the function. 


void matpratr (_MPRT_Template_T *mprt_t, _SYSPTR ctrl_space, char options); 
matpratr (&mptr_t, NULL, options); 


This example shows you the builtin interface. There are 2 builtins that provide 
access to the MATPRATR machine instruction; one in which the process control 
space pointer is omitted and the other in which it is not. If a NULL is passed for 
the second argument on the call to matpratr, the semantics are the same as the 
_MATPRATR1 builtin. 


void _MATPRATR1 (_MPRT_Template_T *mprt_t, char *options); 


void _MATPRATR2 (_MPRT_Template_T *mprt_t, _SYSPTR *ctrl_space, char *options); 


Exception Handling 


Exceptions in the Machine Interface Functional Reference are listed as 2-byte 
hexadecimal numbers as follows: 


22 Object Access <---- Group 
01 Object not found <---- Subtype 
02 Object destroyed 
03 Object suspended 


To monitor for exceptions around calls to MI library functions and builtins you can 
follow steps 1 and 2 or steps 1, 3 and 4: 


1. Convert hex to decimal to determine the correct MCH message. For example, 
hexadecimal 2201 becomes MCH3401. 


2. Use the #pragma exception_handler directive 


3. Find out what C signal the exception maps to. It could be one of SIGPFE, 
SIGILL or SIGSEGV. 


4. Choose to : 


e Ignore the signal. The exception is handled and placed in the joblog. 

¢ Accept the default actions. Using the initial state (SIG_DFL), the exception 
is not handled and percolates. 

¢ Call a signal handler. The exception is handled and is placed in the joblog. 


Example 

This example shows you how exceptions from MI library functions can be moni- 
tored and handled using a signal handling function. The signal handler 
my_signal_handler is registered before the rslvsp function signals a 0x2201 excep- 
tion. When a SIGSEGV signal is raised, the signal handler is called. If an 0x2201 
exception occurred, the signal handler calls the QUSRCRTS API to create a space. 


Machine Interface Library Functions 3 


#include <signal .h> 

#include <QSYSINC/MIH/RSLVSP> 
#include <QSYSINC/H/QUSCRTUS> 
#include <string.h> 

#define CREATION SIZE 65500 
void my_signal_handler(int sig) { 


_INTRPT_Hndlr_Parms_T excp_data; 
int error_code = 0; 


/* Check the message id for exception 0x2201 «/ 
_GetExcData(&excp_ data); 


if (!memcmp(excp_data.Msg Id, "MCH3401", 7)) 


QUSCRTUS("MYSPACE  QTEMP see 
"MYSPACE ", 
CREATION SIZE, 
"vo" r 
"SALL u ; 
"MYSPACE example for Programmer's Reference ae 
"VES iT} ; 


&error_code) ; 


} 
int main(void) { 
_SYSPTR ptr_to_space; 


/* Set up signal handler */ 
signal (SIGSEGV, &my_signal_ handler); 


/* If space is not there, create it using QUSCRTUS API */ 
ptr_to space = rslvsp(_Usrspc, "MYSPACE", "QTEMP", _AUTH_OBJ_MGMT) ; 


/* The rest of the program goes here ... */ 


Using the Templates declared in the MI Header Files 


Some MI instructions require templates that are 16-byte aligned in memory. If a 
template contains a pointer (of any type), a structure of this type will always be 
16-byte aligned. To ensure 16-byte alignment of a template that does not contain a 
pointer, you can do one of two things: 


1. Use malloc to allocate the storage for the template. Storage allocated by 
malloc is always 16-byte aligned. 


2. Declare the template as part of a union whose other member is a pointer. This 
will force 16-byte alignment since the alignment of a union is always that of its 
strictest member. 


Many templates contain variant portions that require the template user to allocate 
the correct amount of storage based on information that is usually not known until 
run time. Consider, for example, the template used for the matobjlk (Materialize 
Object Locks) function. The typedef for MOBJL_Template_T is: 
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typedef Packed struct _MOBJL_ Template T { 


int Template Size; /* size for materialization*/ 
int Bytes_Used; /* size of data available +*/ 
char Lock_Alloc; /* Lock states allocated */ 
char Lock_Synch; /* Lock states Synch Wait */ 
char Lock_Asynch; /* Lock states Asynch Wait */ 
char reserved; 

short Num Descripts; /* # of Lock Descriptors  */ 
char reserved2[2]; 

_LOCK_Descript_T Locks[1]; /* Lock state descriptor(s)*/ 
/* Lock state desciptor is repeated for each lock currently */ 
/* allocated or waited for. This number is given in the */ 
/* Num Descripts field. */ 


} _MOBJL_Template_T; 


The number of lock state descriptors is variable depending upon the number of 
locks currently allocated (or waited for) on the object specified. One way to handle 
the variant portion is to first materialize the information to obtain the number of lock 
state descriptors. This is given by the Num_Descripts field. It is then known 
exactly how much storage you need to allocate in order to materialize all the lock 
state descriptors. If the number of lock state descriptors happens to be three, then 
the following section of code would allocate the storage needed to materialize all 
lock state descriptors. 


/* Allocate storage for template - disregard variant portion */ 
mobjl = (_MOBJL_Template_T *)malloc(sizeof(_MOBJL_Template_T)); 


/* Set all fields in the template to zero. x/ 
memset (mobjl, '\O', sizeof(_MOBJL_ Template T)); 


mobjl->Template_ Size = sizeof(_MOBJL_Template_T); 


/* Materialize to obtain number of lock state descriptors */ 
matobjlk(mobjl, sys[0]); 


/* Calculate size required to hold all lock state descriptors */ 
size = sizeof(_MOBJL Template T) + 
(mobj1->Num Descripts - 1)*sizeof(_LOCK_Descript_T); 


/* Allocate the storage through realloc() */ 
mobjl = (_MOBJL_Template_T *)realloc(mobjl, size); 


/* Set all fields in the template to zero. */ 
memset (mobjl, '\O', sizeof(_MOBJL_ Template T)); 


mobjl->Template_ Size = size; 


/* Materialize again with storage allocated for all descriptors */ 
matobjlk(mobjl, sys[0]); 
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Header Files 


Each MI function and builtin is prototyped in a header file provided in library 
QSYSING, file MIH. If you wish to use the MI instructions and header files, you 
must have the library QSYSINC installed on your system. 


Most of the MI functions and builtins are prototyped in a header file that corre- 
sponds to the MI instruction they reference. For example, the clrbts function is 
declared in library QSYSINC, file MIH, and member CLRBTS. Following is an illus- 
tration of how to include the MI header file that prototypes the clrbts function, from 
the QSYSINC library, in your program: 


#include <QSYSINC/MIH/CLRBTS> 


For ILE C/400, in releases prior to V3R6, the MI functions and builtins were 
declared in header files according to their use (MI group header files). For 
example, all computation functions were in the <micomput.h> header file in library 
QCLE. In V3R6 and following releases, the MI header files reside in the library 
QSYSINC. The H file in QSYSINC contain the MI header files which were previ- 
ously in QCLE (the MI group header files), and these files, in turn, include the indi- 
vidual MI header files. If you have hard coded QCLE/H when including group MI 
header files it is necessary for you to duplicate the MI header files from 
QSYSINC/H to QCLE/H or change your source to remove the QCLE qualification. 
You may be able to reduce compile time by including the header files for individual 
MI instructions rather than the group MI header files. 


Computation and Branching Instructions 
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The following lists the MI header files for computation and branching instructions: 


QSYSINC/MIH/CLRBTS 
QSYSINC/MIH/CPYBYTES 
QSYSINGC/MIH/CPRDATA 
QSYSINC/MIH/CPYNV 
QSYSINC/MIH/CVTBC 
QSYSINC/MIH/CVTCB 
QSYSINC/MIH/CVTCM 
QSYSING/MIH/CVTCS 
QSYSINC/MIH/CVTEFN 
QSYSINC/MIH/CVTMC 
QSYSINC/MIH/RETCA 
QSYSINC/MIH/CVTSC 
QSYSING/MIH/DCPDATA 
QSYSING/MIH/EDIT 
QSYSINC/MIH/EDIT_PACKED 
QSYSINC/MIH/LBCPYNV 
QSYSINC/MIH/SCANX 
QSYSINC/MIH/SETBTS 
QSYSINC/MIH/SETCA 
QSYSINC/MIH/TSTBTS 
QSYSINC/MIH/XLATEWT 
QSYSINC/MIH/CVTCH 
QSYSINC/MIH/CVTHG 
QSYSINC/MIH/CPYBLA 
QSYSINC/MIH/CPYBLAP 


QSYSINC/MIH/CPYHEXNN 
QSYSINC/MIH/CPYHEXNZ 
QSYSINC/MIH/CPYHEXZZ 
QSYSINC/MIH/CPYHEXZN 
QSYSINC/MIH/EXTREXP 
QSYSINGC/MIH/SCANWC 
QSYSINC/MIH/TRIML 
QSYSINC/MIH/EXTREXP 
QSYSINC/MIH/TRIML 
QSYSINC/MIH/XLATEB 


Note: The above header files were previously combined in the header file 
<micomput.h>. 


Date/Time/Timestamp Instructions 
The MI header file for date, time and timestamp instructions is: 


QSYSINC/MIH/MIDTTM 


This header file prototypes all the MI functions and builtins that provide access to 
the Date/Time/Timestamp instructions. 


Note: The declarations in <QSYSINC/MIH/MIDTTM> were previously found in 
<mitime.h>. 


Pointer/Name Resolution Addressing Instructions 
The MI header files for pointer/name resolution addressing instructions are: 
QSYSINC/MIH/CMPPTRA 


QSYSINGC/MIH/CMPPTRT 
QSYSING/MIH/RSLVSP 


Note: The above header files were previously combined in the header file 
<miptrnam.h>. 


Space Object Addressing Instructions 
The MI header files for soace object addressing instructions are: 
QSYSINC/MIH/CMPPSPAD 
QSYSINC/MIH/LSPCO 
QSYSINC/MIH/SETSPFP 
QSYSINC/MIH/SETSPPFP 
QSYSINC/MIH/SETSPPO 
QSYSINC/MIH/STSPPO 
Note: The above header files were previously combined in the header file 
<mispcobj.h>. 


Space Management Instructions 
The MI header files for soace management instructions are: 


QSYSINC/MIH/MATS 
QSYSING/MIH/MODS 


Note: The above header files were previously combined in the header file 
<mispace.h>. 
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Program Management Instructions 
The MI header file for project management instructions is: 


QSYSINC/MIH/MATPG 


Note: The declarations is <QSYSINC/MIH/MATPG=> were previously found in 
<mipgmgmt.h>. 


Program Execution Instructions 
The MI header files for program execution instructions are: 


QSYSINC/MIH/MATACTAT 
QSYSINC/MIH/MATAGPAT 
QSYSINGC/MIH/MODASA 


Note: The above header files were previously combined in the header file 
<mipgexec.h>. 


Independent Index Instructions 
The MI header files for independent index instructions are: 


QSYSINC/MIH/FNDINXEN 
QSYSINC/MIH/INSINXEN 
QSYSINC/MIH/MATINXAT 
QSYSINC/MIH/RMVINXEN 
QSYSINC/MIH/MODINX 


Note: The above header files were previously combined in the header file 
<miindex.h>. 


Queue Management Instructions 
The MI header files for queue management instructions are: 


QSYSINC/MIH/ENQ 
QSYSINC/MIH/DEQ 
QSYSINC/MIH/DEQWAIT 
QSYSINC/MATQMSG 
QSYSING/MIH/MATQAT 


Note: The above header files were previously combined in the header file 
<miqueue.h>. 


Object Lock Management Instructions 
The MI header files for object lock management instructions are: 


QSYSING/MIH/LOCK 
QSYSINC/MIH/LOCKSL 
QSYSINC/MIH/MATAOL 
QSYSINC/MIH/MATOBJLK 
QSYSINC/MIH/MATPRLK 
QSYSINC/MIH/MATSELLK 
QSYSINGC/MIH/UNLOCK 
QSYSINGC/MIH/UNLOCKSL 
QSYSINC/MIH/XFRLOCK 


Note: The above header files were previously combined in the header file 
<milock.h>. 
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Authorization Management Instructions 
The MI header file for authorization management instructions are: 


QSYSINC/MIH/TESTAU 


Note: The declarations in <QSYSINC/MIH/TESTAU> were previously found in 
<miauth.h>. 


Process Management Instructions 
The MI header files for process management instructions are: 
QSYSINC/MIH/MATPRAGP 


QSYSINC/MIH/MATPRATR 
QSYSINC/MIH/WAITTIME 


Note: The above header files were previously combined in the header file 
<miproces.h>. 


Resource Management Instructions 
The MI header files for resource management instructions are: 
QSYSINC/MIH/ENSOBJ 
QSYSINC/MIH/MATAGAT 


QSYSINC/MIH/MATRMD 
QSYSINC/MIH/SETACST 


Note: The above header files were previously combined in the header file 
<mirsc.h>. 


Machine Observation Instructions 
The MI header files for machine observation instructions are: 
QSYSINC/MIH/FNDRINVN 
QSYSINC/MIH/MATINVAT 
QSYSINC/MIH/MATPTR 
QSYSINC/MIH/MATPTRL 
QSYSINC/MIH/MATSOBJ 


Note: The above header files were previously combined in the header file 
<mimchobs.h>. 


Machine Interface Support Instructions 
The MI header files for machine interface support instructions are: 


QSYSINC/MIH/MATMATR 
QSYSINC/MIH/MATMDATA 
QSYSINC/MIH/MATTOD 


Note: The above header files were previously combined in the header file 
<mimchint.h>. 
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Mutex Instructions 


The MI header files for mutex instructions are: 


QSYSINGC/MIH/CRTMTX 
QSYSINGC/MIH/DESMTX 
QSYSINC/MIH/LOCKMTX 
QSYSINC/MIH/MATMTX 
QSYSINC/MIH/MATPRMTX 
QSYSING/MIH/UNLKMTX 


Note: The above header files were previously combined in the header file 
<mimtx.h>. 


Job Information Instructions 


The header file contains the declarations for the job information instructions that 
were previously found in the header file <milib.h>: 


QSYSINC/MIH/MICOMMON 


Original Program Model Description 
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The programming environment provided when the AS/400 system was first intro- 
duced is called the original program model (OPM). Application developers on the 
AS/400 enter source code into a source file and compile that source. If the compi- 
lation is a Success, a program object is created. The set of functions, processes, 
and rules provided by the OS/400 to create and run a program is known as the 
OPM. 


As an OPM compiler generates the program object, it generates additional code. 
The additional code initializes program variables and provides any necessary code 
for special processing that is needed by the particular language. The special pro- 
cessing could include processing any input parameters expected by this program. 
When a program is to start running, the additional compiler-generated code 
becomes the starting point (entry point) for the program. 


Please refer to the /LE Concepts, SC41-4606 for more information on OPM. 


miindex.h 


Independent Index Instructions 


This program illustrates how to call the system API, QUSCRTUI, to create a user 
index. This program must be run before any of the user index examples (insinxen, 
fndinxen, matinxat, modinx and rmvinxen). 


Example 
/#ese cesses sess eect sess eee sl te sue seep oes ees ee scot se */ 
/* */ 
/* Example Group: User Indexes <miindex.h> */ 
/* */ 
/* Function: none (just an example that can be used with */ 
/* the other User Index examples) */ 
/* */ 
/* Description: This program illustrates how to call the system */ 
/* API, QUSCRTUI, to create a user index. This */ 
/* program should be run before any of the user */ 
/* index examples: insinxen, fndinxen, matinxat, */ 
/* modinx, rmvinxen) */ 
/* */ 
/eesepeees eases ees see se sete sete suet se eee ese sees eee se eel se */ 
/* This header file contains */ 
#include <QSYSINC/H/QUSCRTUI> /* the prototype for the */ 


/* QUSCRTUI System API */ 


/* Declare and initialize variables for the call to the QUSCRTUI API. +*/ 


/* Index name and library. */ 

char name_lib[20] = "MYUSRIDX MYLIB ms 
char type[] = "PMs /* Fixed Length Entries */ 
char key_type[] = "1"; /* Insert using "key" */ 
char immediate update[] = "0"; /* No immediate update of index «/ 
char optimize[] = "0" /* Optimize for random referencex/ 
char attribute[10] = "EXAMPLE "3;  /* Arbitrary attribute name.*/ 
char authority[10] = "ALL "; /* Authority for the Index. */ 
char replace[10] = "*NO "s; /* Do not replace the index «/ 
/* if it already exists. */ 
int entry_length = 110, /* Length of each entry. */ 
key_length = 10; /* Length of the key. */ 
char description[50] = "User Index being used for keeping a sorted list"; 
[Roce see ese seus sso se feet es pete see seo pee se ee See eee eee sce Se */ 
/* Define the "error code parameter" structure as defined in the */ 
/* System Programmer's Interface Reference manual. A typedef of a */ 
/* structure in this format is provided in the <QSYSINC/H/QUSEC> */ 
/* header file. The structure typedef is called Qus EC_t and has x/ 
/* different member names than the structure used in this example, */ 
/* although the example could be changed to use that typedef. x*/ 
[Rese See ce east see eee eee bees b eee eee eee eee tee eet ees eee */ 
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struct { 
int bytes_available; 
int bytes_used; 
char exception _id[7]; 
char reserved; 
char exception data[1]; 
} error_code; 


int main(void) { 


/* Call the 'QUSCRTUI' System API to create the user queue with 
/* the specified name and library and the above characteristics. 


/* Let any exception generated 
error_code.bytes available = 0; /* be sent to this program and 
/* appear in the joblog. 


QUSCRTUI( name_lib, attribute, type, entry_length, key type, 
key_length, immediate _update, optimize, authority, 
description, replace, &error_code ); 


miqueue.h 


Queue Management Instructions 


This program illustrates how to call the system API, QUSCRTUQ, to create a user 
queue. This program must be run before any of the user queue examples (eng, 
deq, deqi, matqat and matqmsg). 


Example 
/#ese cesses esos seo sans ee eee sete sue se spe eee ees eet see se */ 
/* */ 
/* Example Group: User Queues <miqueue.h> */ 
/* */ 
/* Function: none (just an example that can be used with */ 
/* the other User Queue examples) */ 
/* */ 
/* Description: This program illustrates how to call the system */ 
/* API, QUSCRTUQ, to create a user queue. This */ 
/* program should be run before any of the user */ 
/* queue examples: enq, deq, deqi, matqat, */ 
/* matqmsg. */ 
/* */ 
/* Since User Queues are often used for inter-job */ 
/* or inter-program communications, the entries on */ 
/* the queue are referred to as "messages". */ 
/* */ 
/eRepe oboe oe eee ee tee eee ee oe Soe eee seo eee eee */ 
/* This header file contains */ 
#include <QSYSINC/H/QUSCRTUQ> /* the prototype for the */ 
/* QUSCRTUQ System API x/ 
/* Declare and initialize variables for the call to the QUSCRTUQ API. +*/ 
/* Since this is not a keyed x/ 
int key_length = 0, /* user queue, set this to zero */ 
maximum_message size = 75, /* Maximum message size x/ 
initial_messages = 10, /* Initial number of messages */ 
additional_messages = 50; /* Number of additional messages */ 
/* that can be accommodated. */ 
char type[] = "PMs /* First-In-First-Out (FIFO)+/ 
/* Library and name of *USRQ*/ 
char name_lib[] = "MYUSRQ MYLIB ms 
char attribute[10] = "EXAMPLE "3;  /* Arbitrary attribute name.*/ 
char authority[10] = "ALL "; /* Authority for the Index. */ 
char replace[10] = "«*NO "s /* Do not replace the queue «/ 
/* if it already exists. */ 
char description[50] = "User Queue used for inter-job communication"; 
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/* Define the "error code parameter" structure as defined in the 
/* System Programmer's Interface Reference manual. A typedef of a 
/* structure in this format is provided in the <QSYSINC/H/QUSEC> 
/* header file. The structure typedef is called Qus EC _t and has 
/* different member names than the structure used in this example, 
/* although the example could be changed to use that typedef. 


struct { 
int bytes_available; 
int bytes_used; 
char exception _id[7]; 
char reserved; 
char exception data[1]; 
} error_code; 


int main(void) { 


/* Call the 'QUSCRTUQ' System API to create the user queue with 
/* the specified name and library and the above characteristics 


/* Let any exception generated 
error_code.bytes available = 0; /* be sent to this program and 
/* appear in the joblog. 


QUSCRTUQ( name_lib, attribute, type, key length, 
maximum_message_ size, initial_messages, 
additional messages, authority, description, 
replace, &error_code ); 


*/ 
*/ 
*/ 
*/ 


*/ 
*/ 
*/ 


atiexit 


Establishing an Invocation Exit Program (ATIEXIT) 


Format 
#include <mipgexec.h> 


int atiexit (_OS_func_t *exit_handler, 
void «parm) 


Description 

The atiexit function will establish an invocation exit handler at the oldest control 
boundary in an activation group. If the control boundary invocation is abnormally 
terminated, the registered exit handler will be invoked. The atiexit function is pro- 
vided for OPM compatibility. 


Invocations cancelled as a result of abort(), CEEMRCR API, RCLACTGRP 
option(*ABNORMAL), process termination, unhandled function check, and 
QMHSNDPM/QMHRSNEW APIs are considered abnormal termination. 


Invocations cancelled as a result of a longjmp(), exit(), RCLACTGRP 
option(*NORMAL) are all considered normal termination. 


When the atiexit function is called, the exit_handler parameter is copied into an 
internal buffer. Any changes made to these parameters after the function is called 
are not reflected. The exit_handler parameter is checked to ensure that it is a valid 
system pointer or NULL (this does not ensure that the system pointer is a valid 
pointer to a program object) If this check fails, the atiexit function returns a 
non-zero value and the previous value of the atiexit function does not change. If it 
succeeds, the exit_handler parameter is copied to an internal buffer, replacing its 
contents. Specifying a NULL pointer for exit_handler is equivalent to turning atiexit 
off. 


Parameters 

exit_handler(input) 
A pointer to an OS_linkage exit handler program. This pointer is copied into an 
internal buffer when the atiexit function is called. Subsequent changes to this 
pointer will not be reflected. 


parm (input) 
A pointer to user data that will be passed to the exit handler. This pointer is 
copied into an internal buffer when the atiexit function is called. Subsequent 
changes to this pointer will not be reflected. 


Notes on Usage 
e The atiexit function cannot be called from within an atiexit-registered handler. 
This will result in a non-zero return value. 


¢ The atiexit function cannot be called from the OPM default activation group. 
This will result in a non-zero return value. 


e The caller of the exit handler acts like a control boundary with regards to 
exception percolation. If an unhandled exception is percolated out of an exit 
handler, then the following is done: 


1. The exception is handled, but the message remains in the joblog. 
2. The *LEFAIL condition is signalled to the caller of the control boundary. 
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Example 

This example illustrates the use of the atiexit function. 

/xeopsoes os ceed esee ee seth see ee eee eee ete eee eee ee 
/* 

/* Example Group: Program Execution <mipgexec.h> 

/* 

/* Function: atiexit 

/* 

/* Description: This example uses ‘atiexit' to establish an 

/* invocation exit handler that will be invoked 

/* when the invocation for main() is abnormally 

/* terminated. 

/* 

Jeeoe een o ete see cso eee eo ee eee ee te eee ce eee eee 


#include <mipgexec.h> 


#pragma linkage(EXIT, 0S) 
void EXIT(void *); 


#pragma linkage(REPORT, OS) 
void REPORT(void); 


int re = 99; 
_OS_func_t *exit_ptr = EXIT; 
main() { 


/* establish the exit handler */ 
atiexit(exit_ptr, &rc); 


/* The rest of the program goes here... */ 


/* Program not found...MCH3401 is generated +*/ 
REPORT(); 


/* Example Group: Program Execution <mipgexec.h> 
/* Function: atiexit - invocation exit handler 


/* Description: This is the invocation exit handler that was 
/* registered through atiexit. 


#include <stdlib.h> 
int main(int argc, char *argv[]) { 
/* Do some cleanup... */ 


exit(*(int *)argv[1]); /* Exit using the return code passed */ 


} 


cdd 


Compute Date Duration (CDD) 


Format 
#include <QSYSINC/MIH/MIDTTM> 


void cdd (_SPCPTR date_duration, 
_SPCPTRCN datel, 
_SPCPTRCN date2, 
_INST_ Template T2 *inst_t); 


Description 

The cdd function computes the date duration. The date specified by date2 is sub- 
tracted from the date specified by date? and the value of the result is placed in 
date_duration. A negative value will be returned when date? is less than date2. 


Parameters 
date_duration (input/output) 
Pointer to the location to receive the packed decimal duration. 


date1 (input) 
Pointer to the first date. 


date2 (input) 
Pointer to the second date. 


inst_t (input) 
Pointer to the instruction template which defines the data definitional attributes 
for date_duration, date1, and date2. 


Notes on Usage 
e The DDATs for date? and date2 must be identical. 
e The builtin function CDD also provides access to the MI instruction. 


e A macro version is available. 
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Example 


This example illustrates the use of the cdd function. 


/* Example Group: 
/* Function: 


/* Description: 


Date/Time/Timestamp <QSYSINC/MIH/MIDTTM> 


cdd (Compute Date Duration) 


This example uses 'cdd' to compute the date 


duration of datel and date2. 


#include <QSYSINC/MIH/MIDTTM> 


#include <string.h> 
#include <stdio.h> 
#include <stdlib.h> 
#include <stddef.h> 


#include <decimal .h> 


/* Internal format for start of Gregorian timeline: January 1, 0001 */ 
#define GREGORIAN TIMELINE START 1721424 


/* Internal format for end of Gregorian timeline: January 1, 10000 


#define GREGORIAN_TIMELINE_END 5373485 


int main(void) { 


_INST_Template_T2 
_DDAT_T 
_Era_Table_T 
_Calendar_Table_T 


char buffer[50]; 
int 

int 

int 

char 


char 
decimal (8,0) 


*inst_t2; 
*ddat_tl, *ddat_t2; 
*xera_t2; 
*cal_t2; 


DDAT_Length, Calendar Offset; 
DDAT_Size, Template Size; 
DDAT_Offset1, DDAT_Offset2; 


source2_d[] = "1992-05-21"; 
sourcel d[] = "1993-01-30"; 
duration; 


DDAT_Length = sizeof(_DDAT_T) + 


2*(sizeof(_Calendar_Table T)) - sizeof(short) + 


sizeof(_Era_ Table T) - 1; 


Calendar_Offset = 


DDAT_Size 7 


Template Size = 


offsetof(_DDAT T, Tables) + 
sizeof(_Era_ Table T); 


2*DDAT_Length + 


2*(sizeof(int)) + /* DDAT Offset */ 


10 + /* reserved4 
sizeof(short) + /* Num_DDATs 
sizeof (int); /* DDAT Size 


*/ 
*/ 
*/ 


*/ 


2*DDAT_Length + offsetof(_INST_Template_T2, DDAT) 


sizeof(int); /* ddat offset */ 

DDAT_Offsetl = (offsetof(_INST Template_T2, DDAT) - 
offsetof(_INST Template T2, DDAT Size)) + 
sizeof(int); /* DDAT2 offset */ 

DDAT_Offset2 = (offsetof(_INST Template_T2, DDAT) - 
offsetof(_INST Template T2, DDAT Size)) + 
DDAT_ Length + sizeof(int); /* DDAT2 offset */ 

inst_t2 = (_INST Template T2 *)malloc(Template Size); 


/* Fill in Instruction Template */ 


memset(inst_t2, '\O', sizeof(_INST_ Template T2)); 


inst_t2->Template Size = Template Size; 
inst_t2->DDAT_1 = 1; 
inst_t2->DDAT_2 = 2; 
inst_t2->DDAT_3 S23 
inst_t2->Length_2 = 10; 
inst_t2->Length_3 = 10; 
inst_t2->DDAT_Size = DDAT_Size; 
inst_t2->Num_DDATs 223 
inst_t2->DDAT_Offset[0] = DDAT Offsetl; 


*(inst_t2->DDAT_Offset + 1)= DDAT_Offset2; 
/* Set table pointers within instruction template */ 


ddat_tl = (_DDAT_T *)&(inst_t2->DDAT Offset + 2); 


ddat_t2 = (_DDATT *)((char *)ddat_t1 + DDAT Length); 
era_t2 = (_Era_Table T *)&(ddat_t2->Tables) ; 

cal_t2 = (Calendar Table T *)((char *)ddat_t2 + Calendar Offset); 
/* Fill in DDAT 1 */ 
ddat_t1->Format_Code = _DATE_DUR; 
ddat_t1->DDAT_Length = DDAT_Length; 
ddat_t1->Calendar_Offset = Calendar Offset; 

/* Fill in DDAT2 x/ 
ddat_t2->DDAT_Length = DDAT_Length; 
ddat_t2->Format_Code = _1S0_DATE; 
ddat_t2->Calendar_Offset = Calendar Offset; 

/* Fill in Era Table for DDAT2 */ 
era_t2->Num_E]ems = 1; 


era_t2->Element[0].Origin_Date = GREGORIAN TIMELINE START; 
era_t2->Element[0].Era_Name[0] = 'A'; 


era_t2->Element[0].Era_Name[1] = 'D'; 

/* Fill in Calendar Table for DDAT2 */ 
cal_t2->Num_Elems = 2; 
cal_t2->Element->Effect_Date = GREGORIAN TIMELINE START; 
cal_t2->Element->Type = 0x0001; 
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memset (cal_t2->Element->reserved, '\0', 10); 
(cal_t2->Element+1)->Effect_Date = GREGORIAN TIMELINE_END; 
(cal_t2->Element+1) ->Type = 0; 

memset ((cal_t2->Element+1)->reserved, '\O', 10); 


cdd(&duration, sourcel_d, source2_d, inst_t2); 


printf("The date duration (YYYYMMDD) is %08D(8,0)\n", duration); 
} 


Output 
The date duration (YYYYMMDD) is 00000809 
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Clear Bit in String (CLRBTS) 


Format 
#include <QSYSINC/MIH/CLRBTS> 


void clrbts (_SPCPTR bit_string, 
unsigned int bit offset); 


Description 
The clrots function clears the bit in bit_string as indicated by bit_offset. 


Parameters 

bit_string (input) 
A pointer to a bit string with the bits numbered left to right from 0 to the total 
number of bits in the string minus 1. 


bit_offset (input) 
Indicates which bit of bit_string is to be set, with an offset of zero indicating the 
leftmost bit of the leftmost byte of bit_string. This value must be less than 64k. 


Notes on Usage 
e If the selected bit is beyond the end of the string, or the value 
of bit_offset is greater than or equal to 64k, the result of the operation 
is undefined. 


e A macro version is available. 
¢ The builtin function CLRBTS also provides access to the MI instruction. 
Exceptions 


In some circumstances, if the selected bit is beyond the end of allocated storage, 
an MCH3203 exception may be signalled. 
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Example 
This example illustrates the use of the clrbts function. 


/* Example Group: Computation and Branching <QSYSINC/MIH/CLRBTS> 


/* 

/* Function: clrbts (Clear Bit in String) 

/* 

/* Description: This example uses 'setbts', 'tstbts', and 

/* ‘clrbts' to set, test, and clear the 17th bit 

/* in the bit string. 

/* 

JeReess noose sas see ese Sees te eee Sh oe pee eee ee tee eee oe ee eee esate 


#include <QSYSINC/MIH/CLRBTS> 
#include <QSYSINC/MIH/SETBTS> 
#include <QSYSINC/MIH/TSTBTS> 
#include <stdio.h> 


#define FALSE 0 
#define TRUE !FALSE 


int main(void) { 
unsigned bit_string = 0; 
unsigned offset = 17; 
unsigned flag = FALSE; 
setbts(&bit_string, offset); 


flag = tstbts(&bit_string, offset); 


if (flag) 
printf("The %u'th bit has been set\n", offset); 


clrbts(&bit_string, offset); 


flag = tstbts(&bit_string, offset); 


if ('flag) 
printf("The Zu'th bit has been cleared\n", offset); 
} 
Output 


The 17'th bit has been set 
The 17'th bit has been cleared 


cmppspad 


Compare Pointer for Space Addressability (CMPPSPAD) 


Format 
#include <QSYSINC/MIH/CMPPSPAD> 


int cmppspad (_SPCPTR spacel, 
_SPCPTR space2) ; 


Description 

The cmppspad function compares space addressability. The space addressability 
contained in the pointer specified by space? is compared with the space address- 
ability defined by space2. If the two data objects pointed to by space1 and space2 
are contained in the same space object, a value of 1 is returned, otherwise, a value 
of 0 is returned. 


Parameters 
space (input) and space2 (input) 
The two space pointers to be compared. 


Notes on Usage 
¢ cmppspad is a compatibility function. Use the cmppspad function for compat- 
ibility only, otherwise use the cmpptra function. The cmpptra function allows 
any type of pointer as arguments. 


e Use C comparison operations to determine, for objects in the same space, if 
the offsets are greater than, less than, or equal. 


e An open pointer that points to any type of pointer is a valid argument. 


Exceptions 
If an invalid space address is given for arguments 1 or 2, an MCH3601 is signalled. 
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Example 
This example illustrates the use of the cmppspad function. 


/* Example Group: Space Object Addressing <QSYSINC/MIH/CMPPSPAD> 


/* 

/* Function: cmppspad (Compare Pointer for Space 

/* Addressability) 

/* 

/* Description: This example uses 'cmppspad' to determine if two 
/* Space pointers are addressing the same space. 

/* 

Jeeoess noose cassettes sees tees eh ost eee eee eee ee ee eee eee eal 


#include <stdio.h> 
#include <QSYSINC/MIH/CMPPSPAD> 


int main(void) { 


int i_array[50], rc; 
_SPCPTR spl = i_array, sp2 = i_array + 25; 


rc = cmppspad(spl, sp2); 


if (rc) 
printf("Objects are in the same space.\n"); 
else 
printf("Objects are not in the same space.\n"); 
} 
Output 


Objects are in the same space. 


cmpptra 


Compare Pointer for Object Addressability (CMPPTRA) 


Format 
#include <QSYSINC/MIH/CMPPTRA> 


int cmpptra (_ANYPTR pointerl, 
_ANYPTR pointer2) ; 


Description 

The cmpptra function compares the object addressability of 2 pointers. The object 

addressed by pointer? is compared with the object addressed by pointer2 to deter- 

mine if both pointers are addressing the same object. A 1 (TRUE) is returned if the 
pointers are addressing the same object, otherwise a 0 (FALSE) is returned. 


For space pointers, TRUE is returned if they are addressing the same space. The 
space offset portion of the pointer is ignored in the comparison. 


For system pointers, TRUE is returned if the system pointer is compared with a 
space pointer that addresses a byte in a space associated with the object that is 
addressed by the system pointer. 


Parameters 
pointer1 (input) 
First pointer for compare operation. Must be a space pointer or system pointer. 


pointer2 (input) 
Second pointer for compare operation. Must be a space pointer or system 
pointer. 


Notes on Usage 
¢ A macro version is available. 


e The builtin function CMPPTRA also provides access to the MI instruction. 
Exceptions 
If a pointer does not exist in argument 1 or 2, an MCH3601 will be signalled. If a 


pointer type other than a system pointer or space pointer is passed, an MCH3602 
will be signalled. 
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Example 

This example illustrates the use of the cmpptra function. 

/eoesses os oeet ese eats ee ee ee esheets e eee */ 
[x */ 
/* Example Group: Pointer/Name Resolution Addressing */ 
/* <QSYSINC/MIH/CMPPTRA> */ 
/* */ 
/* Function: cmpptra (Compare Pointer for Object */ 
/* Addressability) */ 
/* */ 
/* Description: This example uses 'cmpptra' to determine if */ 
/* two pointers are addressing the same object. */ 
/* */ 
/eeoe eee poet ese cose eee be eee eee ee ee eo ee ese nee es */ 


#include <QSYSINC/MIH/CMPPTRA> 
#include <QSYSINC/MIH/RSLVSP> 
#include <QSYSINC/MIH/SETSPPFP> 
#include <stdio.h> 

#include <QSYSINC/H/QUSCRTUS> 
#define CREATION SIZE 65536 


int main(void) { 


_SPCPTR SD; 
_SYSPTR SYSDP3 
int error_code = 0, result; 
QUSCRTUS("MYSPACE QTEMP ", /* Create user space */ 
"MYSPACE on 
CREATION SIZE, 
"\o" ; 
"SALL is 
"MYSPACE example for Programmer's Reference 5 
"£VES ben 


&error_code); 


/* Resolve to created space object */ 
sysp = rslvsp(_Usrspc, "MYSPACE", "QTEMP", AUTH OBJ MGMT); 


sp = setsppfp(sysp); /* Obtain space pointer into space x/ 
result = cmpptra(sp, sysp); 
if (result) 

printf("The pointers are addressing the same object\n"); 


else 
printf("Error: the pointers are NOT addressing the same object\n"); 


cmpptra 


Output 


The pointers are addressing the same object 
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Compare Pointer Type (CMPPTRT) 


Format 
#include <QSYSINC/MIH/CMPPTRT> 


int cmpptrt (_ANYPTR pointer, 
char type); 


Description 

The cmppirt function compares the pointer type with the character scalar. If pointer 
is of the same type as indicated by the character value type, then 1 (TRUE) is 
returned, otherwise 0 (FALSE) is returned. 


Parameters 
pointer (input) 
May be any one of the valid AS/400 pointer types. 


type (input) 
The name of the pointer type to compare to. All valid values are supplied 
through macros in the <milib.h> header file. 


Notes on Usage 
e The builtin function CMPPTRT also provides access to the MI instruction. 


¢ Amacro version is available. 


Exceptions 
If the scalar value supplied for type is not valid, an MCH5003 is signalled. 


Example 
This example illustrates the use of the cmppirt function. 
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/eeseoboe eee eee eet eee oe ee oes Soe eco see ee ees */ 
/* */ 
/* Example Group: Pointer/Name Resolution Addressing */ 
/* #include <QSYSINC/MIH/CMPPTRT> */ 
/* */ 
/* Function: cmpptrt (Compare Pointer Type) */ 
/* */ 
/* Description: This example uses 'cmpptrt' to determine the */ 
/* pointer's type. */ 
/* */ 
[soso essse Sse see ae ees eee este sue eee ete sss ee ob ees ees eoel */ 


#include <QSYSINC/MIH/CMPPTRT> 
#include <stdio.h> 


int main(int arg, char **argv) { 
int result = 0; 
result = cmpptrt(argv[1], _PTR_T NULL); 


if (result) 
printf("The pointer is not set\n"); 
else { 
result = cmpptrt(argv[1], _PTR_T_SYS); 
if (result) 
printf("The pointer is a system pointer\n"); 
else { 
result = cmpptrt(argv[1], _PTR_T_ SPC); 
if (result) 
printf("The pointer is a space pointer\n"); 
else { 
result = cmpptrt(argv[1], _PTR_T_INV); 
if (result) 
printf("The pointer is an invocation pointer\n"); 
else { 
result = cmpptrt(argv[1], _PTR_T PROC); 
if (result) 
printf("The pointer is a function pointer\n"); 
else { 
result = cmpptrt(argv[1], _PTR_T_LBL); 
if (result) 
printf("The pointer is a label pointer\n"); 
else { 
result = cmpptrt(argv[1], _PTR_T_SUSP); 
if (result) 
printf("The pointer is a suspend pointer\n"); 
else 
printf ("Unexpected error\n"); 
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cmpptrt 


Output 
Output if the program is passed the argument NULL: 


The pointer is not set 
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Compress Data (CPRDATA) 


Format 
#include <QSYSINC/MIH/CPRDATA> 


int cprdata (_SPCPTR result, 
int result_length, 
_SPCPTRCN source, 
int src_length); 


Description 

The cprdata function compresses user data of a specified length. If the com- 
pressed result is longer than the result area (as specified by result_length), the 
compression is stopped and only result_length bytes are stored. 


The cprdata function returns the number of bytes in the compressed result. This 
value is always set to the full length of the result, which may be larger than 
result_length. 


Parameters 
result (input/output) 
Pointer to the result area to receive the compressed data. 


result_length (input) 
The result area length. 


source (input) 
The data to be compressed. 


src_length (input) 
The length of the source. 


Notes on Usage 
¢ Only non-pointer data can be compressed, so any pointers in the 
data to be compressed are destroyed in the output of the Decompress 
Data instruction. 


e A simple terse algorithm is used. 


e The builtin function CPRDATA also provides access to the MI instruction. 
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Example 
This example illustrates the use of the cprdata function. 


/* Example Group: Computation and Branching <QSYSINC/MIH/CPRDATA> 
/* Function: cprdata (Compress Data) 


/* Description: This example uses 'cprdata' and 'dcpdata' to 
/* compress then decompress the input string. 


#include <QSYSINC/MIH/CPRDATA> 
#include <QSYSINC/MIH/DCPDATA> 
#include <string.h> 
#include <stdio.h> 


#define SIZE 50 
int main(void) { 


char cpr_data[SIZE]; 

char dpr_data[SIZE] = "Good Day"; 
int clength; 

int dlength; 


clength = cprdata(cpr_data, SIZE, dpr_data, strlen(dpr_data)); 
printf("The compressed length = %d\n", clength); 


dlength = dcpdata(dpr_data, SIZE, cpr_data); 
printf("The decompressed length = %d\n", dlength); 


if (memcmp(dpr_data, "Good Day", strlen(dpr_data)) != 0) 
printf("Error in decompression\n"); 

else 
printf("Decompression successful \n"); 


} 


Output 

The compressed length = 26 
The decompressed length = 8 
Decompression successful 


ctd 


Compute Time Duration (CTD) 


Format 
#include <QSYSINC/MIH/MIDTTM> 


void ctd (_SPCPTR time_duration, 
“SPCPTRCN timel, 
_SPCPTRCN time2, 
_INST_Template_T2 *inst_t); 


Description 

The ctd function determines the time duration. The time specified by time2 is sub- 
tracted from the time specified by time? and the value of the result is placed in 
time_duration. A negative value will be returned when fime7 is less than time2. 


Parameters 
time_duration (input/output) 
Pointer to the location to receive the packed decimal duration. 


time1 (input) 
Pointer to the first time. 


time2 (input) 
Pointer to the second time. 


inst_t (input) 
Pointer to the instruction template which defines the data definitional attributes 
for time_duration, time? and time2. 


Notes on Usage 
e The DDATs for time? and time2 must be identical. 


e The builtin function CTD also provides access to the MI instruction. 


e Amacro version is available. 
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Example 


This example illustrates the use of the ctd function. 


/* Example Group: 
/* Function: 


/* Description: 


Date/Time/Timestamp <QSYSINC/MIH/MIDTTM> 


ctd (Comput Time Duration) 


This example uses 'ctd' to compute the time 


duration of timel and time2. 


#include <QSYSINC/MIH/MIDTTM> 


#include <string.h 
#include <stdio.h> 
#include <stdlib.h 
#include <stddef.h 


#include <decimal .h> 


int main(void) { 


_INST_Template_T 
_DDAT_T 


int 
int 
int 
char 


char 
decimal (6,0) 


> 


> 
> 


2 


*inst_t2; 
*ddat_tl, *ddat_t2; 


DDAT_Length, Calendar Offset; 
DDAT_Size, Template Size; 
DDAT_Offset1, DDAT_Offset2; 


source2_d[] = "11.05.30"; 
sourcel d[] = "14.20.46"; 
duration; 


DDAT_Length = sizeof(_DDAT_T) + 


2*(sizeof(_Calendar_ Table T)) - sizeof(short) + 


sizeof(_Era_ Table T) - 1; 


Calendar_Offset 


DDAT_Size 


Template _Size 


DDAT_Offset1 


DDAT_Offset2 


offsetof(_DDAT T, Tables) + 
sizeof(_Era_ Table T); 


2*DDAT_Length + 


2*(sizeof(int)) + /* DDAT Offset */ 


10 + /* reserved4 
sizeof(short) + /* Num_DDATs 
sizeof (int); /* DDAT Size 


*/ 
*/ 
*/ 


2*DDAT_Length + offsetof(_INST Template_T2, DDAT) + 


sizeof(int); /* ddat offset */ 


(offsetof(_INST Template T2, DDAT) - 


offsetof(_INST Template T2, DDAT Size)) + 


sizeof(int); /* DDAT2 offset */ 


(offsetof(_INST Template T2, DDAT) - 


offsetof(_INST Template T2, DDAT Size)) + 
DDAT_ Length + sizeof(int); /* DDAT2 offset 


inst_t2 = (_INST Template T2 *)malloc(Template Size); 
/* Fill in Instruction Template */ 


memset(inst_t2, '\O', sizeof(_INST Template T2)); 


inst_t2->Template Size = Template Size; 
inst_t2->DDAT_1 = 1; 
inst_t2->DDAT_2 = 2; 
inst_t2->DDAT_3 S23 
inst_t2->Length_2 = 8; 
inst_t2->Length_3 = 8; 
inst_t2->DDAT_Size = DDAT_Size; 
inst_t2->Num_DDATs S25 
inst_t2->DDAT_Offset [0] = DDAT_Offsetl; 


*(inst_t2->DDAT_Offset + 1)= DDAT_Offset2; 


ddat_tl = (_DDAT T *)&(inst_t2->DDAT Offset + 2); 


ddat_t2 = (_DDAT_T *)((char *)ddat_t1 + DDAT Length); 


/* Fill in DDAT 1 */ 


ddat_t1->DDAT_Length DDAT_Length; 


ddat_t1->Format_Code = _TIME_DUR; 
ddat_t1->Hour_Zone = 0; 
ddat_t1->Min_Zone = 0; 


ddat_tl->Calendar_Offset = Calendar_Offset; 


/* Fill in DDAT2 */ 
ddat_t2->DDAT_Length = DDAT_Length; 
ddat_t2->Format_Code = _ISO_TIME; 
ddat_t2->Hour_Zone = 24; 

ddat_t2->Min_Zone = 60; 


ddat_t2->Calendar_Offset = Calendar Offset; 
ctd(&duration, sourcel_d, source2_d, inst_t2); 


printf("The time duration (hhmmss) is %06D(6,0)\n", duration); 
} 


Output 
The time duration (hhmmss) is 031516 
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ctsd 


Compute Timestamp Duration (CTSD) 


36 = MI Library Reference 


Format 
#include <QYSINC/MIH/MIDTTM> 


void ctsd (_SPCPTR timestamp_duration, 
_SPCPTRCN timestampl, 
_SPCPTRCN timestamp2, 
_INST_Template_T2 *inst_t); 


Description 

The ctsd function determines the timestamp duration. The timestamp specified by 
timestamp2 is subtracted from the timestamp specified by timestamp? and the 
value of the result is placed in timestamp_duration. A negative timestamp will be 
returned when timestamp7 is less than timestamp2. 


Parameters 
timestamp_duration (input/output) 
Pointer to the location to receive the packed decimal duration. 


timestamp1 (input) 
Pointer to the first timestamp. 


timestamp2 (input) 
Pointer to the second timestamp. 


inst_t (input) 
Pointer to the instruction template which defines the data definitional attributes 
for timestamp_duration, timestamp1, and timestamp2. 


Notes on Usage 
e The DDATs for timestamp1 and timestamp2 must be identical. 
e The builtin function CTSD also provides access to the MI instruction. 


e Amacro version is available. 


ctsd 


Example 

This example illustrates the use of the ctsd function. 

/ depo Sees sees epee cose see see teehee See eee ces ee eee */ 
/* */ 
/* Example Group: Date/Time/Timestamp <QSYSINC/MIH/MIDTTM> */ 
/* */ 
/* Function: ctsd (Compute Timestamp Duration) */ 
/* */ 
/* Description: This example uses 'ctsd' to compute the timestamp */ 
/* duration of timestampl and timestamp2. */ 
/* */ 
/eReeest esses sset eee ese ee se eee se see eee ee See set eee Sete eee eee */ 


#include <QSYSINC/MIH/MIDTTM> 
#include <string.h> 

#include <stdio.h> 

#include <stdlib.h> 

#include <stddef.h> 

#include <decimal .h> 


/* Internal format for start of Gregorian timeline: January 1, 0001 */ 
#define GREGORIAN TIMELINE START 1721424 


/* Internal format for end of Gregorian timeline: January 1, 10000 +*/ 
#define GREGORIAN TIMELINE END 5373485 


int main(void) { 


_INST_Template_T2 *inst_t2; 
_DDAT_T *ddat_tl, *ddat_t2; 
_Era_Table T xera_t2; 
_Calendar_Table T *cal_t2; 


int DDAT_Length, Calendar Offset; 

int DDAT_Size, Template Size; 

int DDAT_Offset1, DDAT_Offset2; 

char source2_d[] = "1992-02-21-09.15.02.000000"; 
char sourcel_d[] = "1993-11-30-11.22.31.000000"; 
decimal (20,6) duration; 


DDAT_Length = sizeof(_DDAT_T) + 
2*(sizeof( Calendar Table T)) - sizeof(short) + 
sizeof(_Era_ Table T) - 1; 


Calendar Offset = offsetof(_DDAT T, Tables) + 
sizeof(_Era_ Table T); 


DDAT_Size = 2*DDAT_Length + 
2*(sizeof(int)) + /* DDAT Offset */ 
10 + /* reserved4 = */ 
sizeof(short) + /* Num_DDATs */ 
sizeof (int); /* DDAT Size */ 


Template Size = 2*DDAT_Length + offsetof(_INST_Template_T2, DDAT) + 
sizeof(int); /* ddat offset */ 
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DDAT_Offsetl = (offsetof(_INST Template_T2, DDAT) - 
offsetof(_INST Template T2, DDAT Size)) + 
sizeof(int); /* DDAT2 offset */ 

DDAT_Offset2 = (offsetof(_INST Template_T2, DDAT) - 
offsetof(_INST Template T2, DDAT Size)) + 
DDAT_ Length + sizeof(int); /* DDAT2 offset */ 

inst_t2 = (_INST Template T2 *)malloc(Template Size); 


/* Fill in Instruction Template */ 


memset(inst_t2, '\O', sizeof(_INST Template T2)); 


inst_t2->Template Size = Template Size; 
inst_t2->DDAT_1 = 1; 
inst_t2->DDAT_2 = 2; 
inst_t2->DDAT_3 = 2; 
inst_t2->Length_2 = 26; 
inst_t2->Length_3 = 26; 
inst_t2->DDAT_Size = DDAT_Size; 
inst_t2->Num_DDATs = 2; 
inst_t2->DDAT_ Offset [0] = DDAT Offset1; 


*(inst_t2->DDAT_Offset + 1)= DDAT_Offset2; 


ddat_tl1 = (_DDAT_T *)&(inst_t2->DDAT Offset + 2); 


ddat_t2 = (_DDATT *)((char *)ddat_t1 + DDAT Length); 
era_t2 = (_Era_Table T *)&(ddat_t2->Tables); 

cal_t2 = (Calendar Table T *)((char *)ddat_t2 + Calendar Offset); 
/* Fill in DDAT 1 */ 
ddat_t1->DDAT_Length = DDAT_Length; 
ddat_t1->Format_Code = _TIMESTAMP_DUR; 
ddat_t1->Hour_Zone = 0; 

ddat_t1->Min_Zone = 0; 

ddat_t1->Calendar_Offset = Calendar_Offset; 

/* Fill in DDAT2 */ 
ddat_t2->DDAT_Length = DDAT_Length; 
ddat_t2->Format_Code = _SAA_TIMESTAMP; 
ddat_t2->Hour_Zone = 24; 

ddat_t2->Min_Zone = 60; 

ddat_t2->Calendar_Offset = Calendar Offset; 

/* Fill in Era Table for DDAT2 / 
era_t2->Num_Elems = 1; 


era_t2->Element[0].Origin_Date = GREGORIAN TIMELINE START; 
era_t2->Element[0].Era_Name[0] = 'A'; 
era_t2->Element[0].Era_Name[1] = 'D'; 


/* Fill in Calendar Table for DDAT2 */ 


cal_t2->Num_Elems ="25 
cal_t2->Element->Effect_Date GREGORIAN_TIMELINE_START; 
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cal_t2->Element->Type = 0x0001; 
memset (cal_t2->Element->reserved, '\O', 10); 
(cal_t2->Element+1) ->Effect_Date = GREGORIAN TIMELINE_END; 


(cal_t2->Element+1) ->Type = 0; 
memset ((cal_t2->Element+1)->reserved, '\O', 10); 


ctsd(&duration, sourcel_d, source2_d, inst_t2); 
printf("The timestamp duration (YYYYMMDDhhmmssuuuuuu) is %020D(20,6)\n", 


duration); 
} 


Output 
The timestamp duration (YYYYMMDDhhmmssuuuuuu) is 0010909020729 .000000 
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Convert Binary 
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Synchronous Communications to Character (CVTBC) 


Format 
#include <QSYSINC/MIH/CVTBC> 


int cvtbc (_SPCPTR receiver, 
unsigned int revr_length, 
_CVTBC_Control_T «controls, 
_SPCPTRCN source, 
unsigned int src_length); 


Description 

The cvtbc function converts a string value from the BSC (binary synchronous com- 
munications) compressed format to a character string. The function converts 
source using the information contained in controls and places the result into the 
location specified by receiver. 


Parameters 
receiver (input/output) 
Pointer to the location to contain the result of the conversion. 


revr_length (input) 
The length of the receiver. The length must be between 1 and 32767. 


controls (input/output) 
Pointer to the controls template containing additional information for the conver- 
sion. 


source (input) 
Pointer to the location containing the source in BSC compressed format. 


src_length (input) 
The length of the source. The length must be between 1 and 32767. 


Notes on Usage 
¢ The builtin function CVTBC also provides access to the MI instruction. 


Return Code 
Values returned by the function cvtbc are set as follows: 


Value Meaning 

-1 Completed Record 
0 Source Exhausted 
1 Truncated Record 


cvibc 


Example 

This example illustrates the use of the cvtbc function. 

/ eee Sees ese es eee cess ee settee cee eee eee cee eee */ 
/* */ 
/* Example Group: Computation and Branching <QSYSINC/MIH/CVTBC> */ 
/* */ 
/* Function: cvtbc (Convert BSC to Character) x/ 
/* */ 
/* Description: This example uses 'cvtcb' and 'cvtbc' to */ 
/* convert the input string from character to BSC */ 
/* format then back to character format. */ 
/* */ 
[Resse sasSoe eset cee eee ee se eee ee ee eee eee See ee eee ete eee eee */ 


#include <QSYSINC/MIH/CVTBC> 
#include <QSYSINC/MIH/CVTCB> 
#include <string.h> 
#include <stdio.h> 


#define SIZE 50 
int main(void) { 


_CVTCB_Control_T cvtcb_t = {@, 0x01}; 
_CVTBC_Control_T cvtbc_t = {0, 0x01}; 


char cb[SIZE] = "This is the input string"; 
char bc[SIZE] ; 
int be_rc, cb_rc; 


cb_rc = cvtcb(bc, SIZE, &cvtcb_t, cb, SIZE); 
printf("The return code from cvtcb is %d\n", cb_rc); 


be_rc = cvtbc(cb, SIZE, &cvtbc_t, bc, SIZE); 
printf("The return code from cvtbc is %d\n", bc_rc); 


if (memcmp(cb, "This is the input string", strlen(cb)) !=0 ) 
printf("Error in conversion\n"); 

else 
printf("Conversion successful\n") ; 


} 
Output 


The return code from cvtcb is 0 
The return code from cvtbc is 0 
Conversion successful 
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Convert Character to Binary Synchronous Communications (CVTCB) 


42 Ml Library Reference 


Format 
#include <QSYSINC/MIH/CVTCB> 


int cvtcb (_SPCPTR receiver, 
unsigned int revr_length, 
_CVTCB_Control_T «controls, 
_SPCPTRCN source, 
unsigned int src_length); 


Description 

The cvtcb function converts a string value from character to BSC (binary synchro- 
nous communications) compressed format. The function converts source using the 
information contained in controls and places the result into the location specified by 
receiver. 


Parameters 
receiver (input/output) 
Pointer to the location to contain the result of the conversion. 


revr_length (input) 
Length of the receiver. Length must be between 1 and 32767. 


controls (input/output) 
Pointer to the controls template containing additional information for the conver- 
sion. 


source (input) 
Pointer to the location containing the source string to be converted. 


src_length (input) 
The length of the source. The length must be between 1 and 32767. 


Notes on Usage 
e The builtin function CVTCB also provides access to the MI instruction. 


Return Code 
Values returned by the function cvtcb are set as follows: 


Value Meaning 
-1 Receiver Overrun 
0 Source Exhausted 


cvicb 


Example 

This example illustrates the use of the cvtcb function. 

/ eee Se ehe sss es eee coe s ee settee cee eee eee se see eee */ 
/* */ 
/* Example Group: Computation and Branching <QSYSINC/MIH/CVTCB>  */ 
/* */ 
/* Function: cvtcb (Convert Character to BSC) */ 
/* */ 
/* Description: This example uses 'cvtcb' and 'cvtbc' to */ 
/* convert the input string from character to BSC */ 
/* format then back to character format. */ 
/* */ 
[Resse sas See Stet cee eee ee eee ee ee eee ee See ee eee ese eee ee */ 


#i 
#i 
#i 
#i 
#d 


in 


} 
O 


nclude <QSYSINC/MIH/CVTCB> 
nclude <QSYSINC/MIH/CVTBC> 
nclude <string.h> 
nclude <stdio.h> 


efine SIZE 50 
t main(void) { 


_CVTCB_Control_T cvtcb_t = {@, 0x01}; 
_CVTBC_Control_T cvtbc_t = {0, 0x01}; 


char cb[SIZE] = "This is the input string"; 
char bc[SIZE] ; 
int be_rc, cb_rc; 


cb_rc = cvtcb(bc, SIZE, &cvtcb_t, cb, SIZE); 
printf("The return code from cvtcb is %d\n", cb_rc); 


be_rc = cvtbc(cb, SIZE, &cvtbc_t, bc, SIZE); 
printf("The return code from cvtbc is %d\n", bc_rc); 


if (memcmp(cb, "This is the input string", strlen(cb)) !=0 ) 
printf("Error in conversion\n"); 

else 
printf("Conversion successful\n") ; 


utput 


The return code from cvtcb is 0 
The return code from cvtbc is 0 
Conversion successful 
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Convert Eight Bit Character to Hex Nibbles (CVTCH) 


44 Ml Library Reference 


Format 
#include <QSYSINC/MIH/CVTCH> 


void cvtch (_SPCPTR receiver, 
_SPCPTRCN source, 
int size); 


Description 
The cvtch function takes each character (8-bit value) of source and converts it to a 
hexadecimal digit (4-bit value) and places into receiver. 


Parameters 
receiver (input/output) 
Pointer to a 4-bit hexadecimal receiver. 


source (input) 
Pointer to an 8-bit character source. 


size (input) 
The length in bytes of the source. 


Notes on Usage 
e The characters in source must relate to valid hexadecimal digits or an excep- 
tion is signaled. 


Characters Hex digits 
Hex FO-Hex F9 = Hex 0-Hex 9 
Hex C1-Hex C6 = Hex A-Hex F 


e This is a compatibility function to provide the same semantics as the CVTCH 
MI instruction. 


¢ If 0 is specified as size, no action is taken. 


Exceptions 
If any of the input characters are specified incorrectly, an MCH3601 or MCHO601 
will be signalled. 


Other exceptions possible from this function are: 


MCH0602 - Boundary alignment 

MCH0801 - Parameter Reference Violation 
MCH3402 - Object Destroyed 

MCH3602 - Pointer Type Invalid 

MCH6801 - Object Domain Violation 


cvtch 


Example 

This example illustrates the use of the cvtch function. 

/ eee Se eh ess sees epee coe s ee see tee eee eee eee sece eee */ 
/* */ 
/* Example Group: Computation and Branching <QSYSINC/MIH/CVTCH> */ 
/* */ 
/* Function: cvtch (Convert Character to Hexadecimal) */ 
/* */ 
/* Description: This example uses 'cvtch' and 'cvthc' to */ 
/* convert the input string from character to */ 
/* hexadecimal then back to character. */ 
/* */ 
[Resse sass ee Stet eee eee ee se ee ee ee eee eee eee tee eee ee eee eee ee */ 
#include <QSYSINC/MIH/CVTCH> 

#include <QSYSINC/MIH/CVTHC> 

#include <string.h> 

#include <stdio.h> 


int main(void) { 


char 
char 


char 
char 


c_array[9] = "A93B1FECD"; 
h_array[6] = {0xA9, 0x3B, Ox1F, OxEC, OxDO, 0x00}; 


char_array[9]; 
hex_array[6] ; 


memcpy(char_array, c_array, sizeof(char_array)); 


cvtch(hex_array, char_array, sizeof(char_array)); 


if (memcmp(hex_array, h_array, sizeof(hex_array)) != 0) 
printf("Error in conversion\n"); 


cvthc(char_array, hex_array, sizeof (hex_array)*2); 


if (memcmp(char_array, c_array, sizeof(char_array)) != 0) 
printf("Error in conversion\n"); 


} 


Output 


** no screen output ** 
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Convert a Character String to Multi-Leaving Remote Job Entry 


(CVTCM) 


46 Ml Library Reference 


Format 
#include <QSYSINC/MIH/CVTCM> 


int cvtcm (_SPCPTR receiver, 
unsigned int rcevr_length, 
_CVTCM_Control_T «controls, 
_SPCPTRCN source, 
unsigned int src_length); 


Description 

The cvtcm function converts a string of characters to Multi-Leaving Remote Job 
Entry (MRJE) compressed format. The information supplied in the controls is used 
to guide the conversion. 


Parameters 
receiver (input/output) 
Pointer to the storage location to receive the results of the conversion. 


revr_length (input) 
Length of receiver. Length must be between 1 and 32767. 


controls (input/output) 
Pointer to the controls template. 


source (input) 
Pointer to the source. 


src_length (input) 
The length of the source to be converted. The length must be between 1 and 
32767. 


Notes on Usage 
e The builtin function CVTCM also provides access to the MI instruction. 


Return Code 
Values returned by the function cvtcm are: 


Value Meaning 
-1 Receiver Overrun 
0 Source Exhausted 
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Example 

This example illustrates the use of the function cvtcm. 

/ eeSe Se eh ess sees eee cose see te eee cece eee cee eee. */ 
/* */ 
/* Example Group: Computation and Branching <QSYSINC/MIH/CVTCM> */ 
/* */ 
/* Function: cvtcm (Convert Character to MRJE) */ 
/* */ 
/* Description: This example uses 'cvtcm' and 'cvtmc' to convert */ 
/* the input string from character format to MRJE */ 
/* format then back to character format. */ 
/* */ 
[Resse sassee eset cee eee ee ce eee ee se eee ee Ses ee eee ete eee ee */ 


#include <QSYSINC/MIH/CVTCM> 
#include <QSYSINC/MIH/CVTMC> 
#include <string.h> 
#include <stdio.h> 


#define SIZE 50 


int main(void) { 


char cm[SIZE] = "This is the input string"; 

char mc[SIZE]; 

_CVTCM Control _T cvtcm_t = {0,0, 0x00, 0x10, 0x00, 0x00, 0x00, 
Oxfl}; 

_CVTMC_Control_T cvtmc_t = {0,0, 0x00, 0x10}; 

int cm_rc, mc_rc3; 


cm_rc = cvtcm(mc, SIZE, &cvtcm_t, cm, strlen(cm)); 
printf("The return code from cvtcm is %d\n", cm_rc); 


mc_rc = cvtmc(cm, SIZE, &cvtmc_t, mc, cvtcm_t.Receiver) ; 
printf("The return code from cvtmc is %d\n", mc_rc); 


if (memcmp(cm, "This is the input string", strlen(cm)) != 0) 
printf("Error in conversion\n"); 
else 


printf("Conversion successful\n") ; 
} 


Output 

The return code from cvtcm is 0 
The return code from cvtmc is 0 
Conversion successful 
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cvtcs 


Convert a Character String to System Network Architecture (CVTCS) 


Format 
#include <QSYSINC/MIH/CVTCS> 


int cvtcs (_SPCPTR receiver, 
unsigned int revr_length, 
_CVTCS Control_T *controls, 
_SPCPTRCN source, 
unsigned int src_length); 


Description 

The cvtcs function converts the source from character format to Systems Network 
Architecture (SNA) format. The information supplied in controls is used to guide 
the conversion. 


Parameters 
receiver (input/output) 
Pointer to the storage location to receive the results of the conversion. 


revr_length (input) 
Length of the receiver. The length must be between 1 and 32767. 


controls (input/output) 
Pointer to the controls template. 


source (input) 
Pointer to the source. 


src_length (input) 
The length of the source. The length must be between 1 and 32767. 


Notes on Usage 
¢ The builtin function CVTCS also provides access to the MI instruction. 


Return Code 
Values returned by the function cvtcs are: 


Value Meaning 
-1 Receiver Overrun 
0 Source Exhausted 
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Example 

This example illustrates the use of the cvtcs function. 

/ ees Sees espe s eee cose see settee ee eee eee eee eee eee. */ 
/* */ 
/* Example Group: Computation and Branching <QSYSINC/MIH/CVTCS> */ 
/* */ 
/* Function: cvtcs (Convert Character to SNA) */ 
/* */ 
/* Description: This example uses ‘cvtcs' and 'cvtsc' to convert */ 
/* from character format to SNA format then back */ 
/* to character format. */ 
/* */ 
[Resse sass ee eset cee eee ee eee ee eee eee eee cee ee ee ee ete eee ee */ 


#include <QSYSINC/MIH/CVTCS> 
#include <QSYSINC/MIH/CVTSC> 
#include <string.h> 
#include <stdio.h> 


#define SIZE 50 


int main(void) { 


char cs[SIZE] = "This is the input string"; 
char sc[SIZE]; 
int cs_rc, SC_rc3 


_CVTCS Control _T cvtcs_ t = {0,0, 0x80, 0x20, 0x00, 0x00, 0x00, 
Qx34, 0x40, 0x40}; 

_CVTSC_Control_T cvtsc_t = {0,0, 0x80, 0x32, 0x34, 0x00, 0x00, 
_CVTSC_CONVERT_NO_TRANS, 0x00, 0}; 


cs_rc = cvtcs(sc, SIZE, &cvtcs_t, cs, strlen(cs)); 
printf("The return code from cvtcs is %d\n", cs_rc); 


sc_rc = cvtsc(cs, SIZE, &cvtsc_t, sc, cvtcs_t.Receiver); 
printf("The return code from cvtsc is %d\n", sc_rc); 


if (memcmp(cs, "This is the input string", strlen(cs)) != 0) 
printf("Error in conversion\n"); 

else 
printf("Conversion successful\n") ; 


} 
Output 


The return code from cvtcs is 0 
The return code from cvtsc is 0 
Conversion successful 
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cvid 


Convert Date (CVTD) 
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Format 
#include <QSYSINC/MIH/MIDTTM> 


void cvtd (_SPCPTR result date, 
_SPCPTRCN source_date, 
_INST_Template_Tl *inst_t); 


Description 

The cvtd function converts one calendar date to another calendar date. The date 
specified in source_date is converted to another calendar external or internal pres- 
entation and placed in result_date. 


Parameters 
result_date (input/output) 
Pointer to the location to receive the converted date. 


source_date (input) 
Pointer to the source date. 


inst_t (input) 
Pointer to the instruction template which defines the data definitional attributes 
for result_date and source_date. 


Notes on Usage 
e The builtin function CVTD also provides access to the MI instruction. 


e Amacro version is available. 


cvid 


Example 

This example illustrates the use of the cvtd function. 

/ sep Sees sss eee cose see settee eee See eee ces ee eee */ 
/* */ 
/* Example Group: Date/Time/Timestamp <QSYSINC/MIH/MIDTTM> */ 
/* */ 
/* Function: cvtd (Convert Date) */ 
/* */ 
/* Description: This example uses 'cvtd' to convert a calendar */ 
/* date from ISO format to USA format. */ 
/* */ 
/xReesst esl cee Stet eee eee se eee se eee eee ee see eee ee eet eee eee */ 


#include <QSYSINC/MIH/MIDTTM> 
#include <string.h> 
#include <stdio.h> 
#include <stdlib.h> 
#include <stddef.h> 


/* Internal format for start of Gregorian timeline: January 1, 0001 


/ 
#define GREGORIAN TIMELINE START 1721424 
/* Internal format for end of Gregorian timeline: January 1, 10000 */ 


#define GREGORIAN TIMELINE END 5373485 
int main(void) { 


_INST_Template_T1l *inst_tl; 

_DDAT_T *ddat_tl, *ddat_t2; 
_Era_Table T *xera_tl, *era_t2; 
_Calendar_Table T *cal_tl, *cal_t2; 


int DDAT_Length, Calendar Offset; 
int DDAT_Size, Template Size; 

int DDAT_Offset1, DDAT_Offset2; 
char result_d[10]; 

char source d[10] = "1993-01-17"; 


DDAT_Length = sizeof(_DDAT_T) + 
2*(sizeof( Calendar Table T)) - sizeof(short) + 
sizeof(_Era_ Table T) - 1; 


Calendar Offset = offsetof(_DDAT T, Tables) + 
sizeof(_Era_ Table T); 


DDAT_Size = 2*DDAT_Length + 
2*(sizeof(int)) + /* DDAT Offset */ 
10 + /* reserved4 = */ 
sizeof(short) + /* Num_DDATs */ 
sizeof (int); /* DDAT Size */ 


Template Size = 2*DDAT_Length + offsetof(_INST_Template_Tl, DDAT) + 
sizeof(int); /* ddat offset */ 
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DDAT_Offsetl = (offsetof(_INST Template_T1, DDAT) - 
offsetof(_INST Template _T1, DDAT Size)) + 
sizeof(int); /* DDAT2 offset */ 

DDAT_Offset2 = (offsetof(_INST Template_T1, DDAT) - 
offsetof(_INST Template _T1, DDAT Size)) + 
DDAT_ Length + sizeof(int); /* DDAT2 offset */ 

inst_tl = (_INST_Template_Tl *)malloc(Template Size); 


/* Fill in Instruction Template */ 


memset(inst_tl, '\O', sizeof(_INST Template Tl)); 


inst_tl->Template Size = Template Size; 
inst_t1->DDAT_1 = 1; 
inst_t1->DDAT_2 = 2; 
inst_t1l->Length_1 = 10; 
inst_tl->Length_2 = 10; 
inst_t1->DDAT_Size = DDAT_Size; 
inst_t1l->Num_DDATs = 2; 
inst_t1->DDAT_ Offset [0] = DDAT Offset1; 


*(inst_t1->DDAT_Offset + 1)= DDAT_Offset2; 


ddat_tl = (_DDAT_T *)&(inst_t1->DDAT Offset + 2); 


era_tl = (_Era_Table T *)&(ddat_t1->Tables) ; 

cal_tl = (Calendar Table T *)((char *)ddat_t1 + Calendar Offset); 
ddat_t2 = (_DDATT *)((char *)ddat_t1 + DDAT Length); 

era_t2 = (_Era_Table T *)&(ddat_t2->Tables); 

cal_t2 = (Calendar Table T *)((char *)ddat_t2 + Calendar Offset); 
/* Fill in DDAT1 */ 
ddat_t1->DDAT_Length = DDAT_Length; 

ddat_t1->Format_Code = _USA_DATE; 

ddat_t1->Calendar_Offset = Calendar Offset; 

/* Fill in Era Table for DDAT1 */ 
era_tl->Num_Elems = 1; 


era_t1->Element[0].Origin_Date = GREGORIAN TIMELINE START; 
era_t1->Element[0].Era_Name[0] 'A'; 
era_t1->Element[0].Era_Name[1] = 'D'; 


/* Fill in Calendar Table for DDAT1 */ 
cal_t1->Num_Elems = 25 
cal_tl->Element->Effect_Date = GREGORIAN_ TIMELINE START; 
cal_tl->Element->Type = 0x0001; 

memset (cal_t1->Element->reserved, '\O', 10); 
(cal_t1->Element+1)->Effect_Date = GREGORIAN TIMELINE_END; 
(cal_t1->Element+1) ->Type = 0; 

memset ((cal_t1->Element+1)->reserved, '\O', 10); 

/* Fill in DDAT2 */ 
ddat_t2->DDAT_Length = DDAT_Length; 
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ddat_t2->Format_Code _ISO_DATE; 
ddat_t2->Calendar_Offset = Calendar Offset; 


/* Fill in Era Table for DDAT2 x/ 


era_t2->Num_E]lems ely 
era_t2->Element[0].Origin_Date = GREGORIAN TIMELINE START; 
era_t2->Element[0].Era_Name[0] = 'A'; 
era_t2->Element[0].Era_Name[1] = 'D'; 


/* Fill in Calendar Table for DDAT2 x/ 
cal_t2->Num_Elems = 2; 
cal_t2->Element->Effect_Date = GREGORIAN_TIMELINE_START; 
cal_t2->Element->Type = 0x0001; 

memset (cal_t2->Element->reserved, '\O', 10); 
(cal_t2->Element+1) ->Effect_Date = GREGORIAN TIMELINE_END; 


(cal_t2->Element+1)->Type = 0; 
memset ((cal_t2->Element+1)->reserved, '\O', 10); 


cvtd(result_d, source _d, inst_t1); 
result_d[10] = '\0'; 


printf("The converted date is %s\n", result_d); 


} 


Output 
The converted date is 01/17/1993 
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Convert External Form to Numeric Value (CVTEFN) 
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Format 
#include <QSYSINC/MIH/CVTEFN> 


int cvtefni (_SPCPTRCN source, 
unsigned int src_length, 
char mask[3]); 


double cvtefnd (_SPCPTRCN source, 
unsigned int src_length, 
char mask[3]); 


Description 

The cvtefni and cvtefnd functions scans a character string for a valid decimal 
number in display format, removes the display character, and converts the result to 
integer (in the case of cvtefni) or double (in the case of cvtefnd). 


Parameters 
source (input) 
The character string value. A valid decimal number in display format. 


src_length (input) 
Length in bytes of source. The length must be between 1 and 32767. 


mask (input) 
The 3-byte character mask used in the conversion. Byte 1 of the mask indi- 
cates the byte value that is to be used for the currency symbol. Byte 2 of the 
mask indicates the byte value to be used for the comma symbol. Byte 3 of the 
mask indicates the byte value to be used for the decimal point symbol. 


Notes on Usage 
e The builtin functions CVTEFN1 and CVTEFN2 also provide access to the MI 
instruction. 
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Example 

This example illustrates the use of the cvtefn function. 

/ dese Sees ese s epee coe see see tee cee ee eee cee eee. */ 
/* */ 
/* Example Group: Computation and Branching <QSYSINC/MIH/CVTEFN> = */ 
/* */ 
/* Function: cvtefni/d (Convert External Form to Numeric) */ 
/* */ 
/* Description: This example uses 'cvtefni' to convert from */ 
/* external form to numeric integer and 'cvtefnd' */ 
/* to convert from external form to numeric double. +*/ 
/* */ 
[eesee sass eset cee eee ee eee eee see eee ee See se eee eee cee ee */ 


#include <QSYSINC/MIH/CVTEFN> 
#include <string.h> 
#include <stdio.h> 


int main(void) { 


int integer_result; 

double double result; 

char integer_source[] = "$6,025"; 
char double _source[] = "$1,605.25"; 
char mask[y, = "$52" 


integer_result = cvtefni(integer_source, strlen(integer_source), mask); 
printf("The integer result is %d\n", integer_result); 


double_result = cvtefnd(double source, strlen(double source), mask); 
printf("The double result is %1f\n", double result); 


} 


Output 
The integer result is 6025 
The double result is 1605.250000 
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Format 
#include <QSYSINC/MIH/CVTHC> 


void cvthc (_SPCPTR receiver, 
_SPCPTRCN source, 
int size); 


Description 
The cvthc function takes each hexadecimal digit (4- bit value) of source and con- 
verts it to a character digit (8-bit value) and places into receiver. 


Parameters 
receiver (input/output) 
Pointer to an 8-bit character value. 


source (input) 
Pointer to a 4-bit hexadecimal value. 


size (input) 
The length in nibbles of the source. 


Notes on Usage 
e The characters in source must relate to valid hexadecimal digits or an excep- 
tion is signaled. 


Hex Digits Characters 
Hex 0-Hex 9 = Hex FO-Hex F9 
Hex A-Hex F = Hex C1-Hex C6 


¢ This is a compatibility function to provide the same semantics as the CVTHC 
MI instruction. 


¢ If 0 is specified as size, no action is taken. 


Exceptions 
If any of the input characters are specified incorrectly, an MCH3601 or MCHO601 
will be signalled. 


Other exceptions possible from this function are: 


MCH0602 - Boundary alignment 

MCH0801 - Parameter Reference Violation 
MCH3402 - Object Destroyed 

MCH3602 - Pointer Type Invalid 

MCH6801 - Object Domain Violation 
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Example 

This example illustrates the use of the cvthc function. 

/ eee Se eh es soe es epee coe see settee eee eee eee ees eee */ 
/* */ 
/* Example Group: Computation and Branching <QSYSINC/MIH/CVTHC> */ 
/* */ 
/* Function: cvthc (Convert Hexadecimal to Character) */ 
/* */ 
/* Description: This example uses 'cvtch' and 'cvthc' to */ 
/* convert the input string from character to */ 
/* hexadecimal then back to character. */ 
/* */ 
[Resse sass eset cee eee ee se eee el ee se ee eee eee ee eet eee ee */ 
#include <QSYSINC/MIH/CVTHC> 

#include <QSYSINC/MIH/CVTCH> 

#include <string.h> 

#include <stdio.h> 


int main(void) { 


char 
char 


char 
char 


c_array[9] = "A93B1FECD"; 
h_array[6] = {0xA9, 0x3B, Ox1F, OxEC, OxDO, 0x00}; 


char_array[9]; 
hex_array[6] ; 


memcpy(char_array, c_array, sizeof(char_array)); 


cvtch(hex_array, char_array, sizeof(char_array)); 


if (memcmp(hex_array, h_array, sizeof(hex_array)) != 0) 
printf("Error in conversion\n"); 


cvthc(char_array, hex_array, sizeof (hex_array)*2); 


if (memcmp(char_array, c_array, sizeof(char_array)) != 0) 
printf("Error in conversion\n"); 


} 


Output 


** no screen output ** 
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cvtmc 


Convert Multi-Leaving Remote Job Entry to Character (CVTMC) 


Format 
#include <QSYSINC/MIH/CVTMC> 


int cvtmc (_SPCPTR receiver, 
unsigned int revr_length, 
_CVTMC_Control_T «controls, 
_SPCPTRCN source, 
unsigned int src_length); 


Description 

The cvtmc function converts a character string from Multi-Leaving Remote Job 
Entry (MRJE) compressed format to character format. The information supplied in 
the controls is used to guide the conversion. 


Parameters 
receiver (input/output) 
Pointer to the storage location to receive the results of the conversion. 


revr_length (input) 
Length of the receiver. The length must be between 1 and 32767. 


controls (input/output) 
Pointer to the controls template. 


source (input) 
Pointer to the source. 


src_length (input) 
Length of the source, including the null terminator. The length must be 
between 1 and 32767. 


Notes on Usage 
e The builtin function CVTMC also provides access to the MI instruction. 


Return Code 
Values returned by the function cvtmc are: 


Value Meaning 
-1 Receiver Overrun 
0 Source Exhausted 
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Example 

This example illustrates the use of the cvtmc function. 

/ dese Se ehe ss sees epee cose see settee eee cee eee ese eee */ 
/* */ 
/* Example Group: Computation and Branching <QSYSINC/MIH/CVTMC> */ 
/* */ 
/* Function: cvtmc (Convert MRJE to Character) */ 
/* */ 
/* Description: This example uses 'cvtcm' and 'cvtmc' to convert */ 
/* the input string from character format to MRJE */ 
/* format then back to character format. */ 
/* */ 
[Resse sass stat eee ee ee se eee ee ee eee ee See ee eee eee eee ee */ 


#include <QSYSINC/MIH/CVTMC> 
#include <QSYSINC/MIH/CVTCM> 
#include <string.h> 
#include <stdio.h> 


#define SIZE 50 


int main(void) { 


char cm[SIZE] = "This is the input string"; 

char mc[SIZE]; 

_CVTCM Control _T cvtcm_t = {0,0, 0x00, 0x10, 0x00, 0x00, 0x00, 
Oxfl}; 

_CVTMC_Control_T cvtmc_t = {0,0, 0x00, 0x10}; 

int cm_rc, mc_rc3; 


cm_rc = cvtcm(mc, SIZE, &cvtcm_t, cm, strlen(cm)); 
printf("The return code from cvtcm is %d\n", cm_rc); 


mc_rc = cvtmc(cm, SIZE, &cvtmc_t, mc, cvtcm_t.Receiver) ; 
printf("The return code from cvtmc is %d\n", mc_rc); 


if (memcmp(cm, "This is the input string", strlen(cm)) != 0) 
printf("Error in conversion\n"); 
else 


printf("Conversion successful\n") ; 
} 


Output 

The return code from cvtcm is 0 
The return code from cvtmc is 0 
Conversion successful 
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Convert System Network Architecture to Character (CVTSC) 


Format 
#include <QSYSINC/MIH/CVTSC> 


int cvtsc (_SPCPTR receiver, 
unsigned int rcevr_length, 
_CVTSC_Control_T *controls, 
_SPCPTRCN source, 
unsigned int src_length); 


Description 

The cvtsc function converts a character string from Systems Network Architecture 
(SNA) format to character format. The information supplied in controls is used to 
guide the conversion. 


Parameters 
receiver (input/output) 
Pointer to the storage location to receive the results of the conversion. 


revr_length (output) 
Length of the receiver. The length must be between 1 and 32767. 


controls (input/output) 
Pointer to the controls template. 


source (input) 
Pointer to the source. 


src_length (input) 
Length of the source. The length must be between 1 and 32767. 


Notes on Usage 
e The builtin function CVTSC also provides access to the MI instruction. 


Return Code 
Values returned by the function cvtsc are: 


Value Meaning 

-1 Receiver Overrun 

0 Source Exhausted 

1 Escape Code Encountered 
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Example 

This example illustrates the use of the cvtsc function. 

/ dese Se eh es sss eee cose see see tose eee ee eee ee eee eee */ 
/* */ 
/* Example Group: Computation and Branching <QSYSINC/MIH/CVTSC> */ 
/* */ 
/* Function: cvtsc (Convert SNA to Character) */ 
/* */ 
/* Description: This example uses 'cvtcs' and 'cvtsc' to convert */ 
/* from character format to SNA format then back */ 
/* to character format. */ 
/* */ 
[Resse sass ee eset eee eee ee eee ee eee eee cee ee ee ete eee eee */ 


#include <QSYSINC/MIH/CVTSC> 
#include <QSYSINC/MIH/CVTCS> 
#include <string.h> 
#include <stdio.h> 


#define SIZE 50 


int main(void) { 


char cs[SIZE] = "This is the input string"; 
char sc[SIZE]; 
int cs_rc, SC_rc3 


_CVTCS Control _T cvtcs_ t = {0,0, 0x80, 0x20, 0x00, 0x00, 0x00, 
Qx34, 0x40, 0x40}; 

_CVTSC_Control_T cvtsc_t = {0,0, 0x80, 0x32, 0x34, 0x00, 0x00, 
_CVTSC_CONVERT_NO_TRANS, 0x00, 0}; 


cs_rc = cvtcs(sc, SIZE, &cvtcs_t, cs, strlen(cs)); 
printf("The return code from cvtcs is %d\n", cs_rc); 


sc_rc = cvtsc(cs, SIZE, &cvtsc_t, sc, cvtcs_t.Receiver); 
printf("The return code from cvtsc is %d\n", sc_rc); 


if (memcmp(cs, "This is the input string", strlen(cs)) != 0) 
printf("Error in conversion\n"); 

else 
printf("Conversion successful\n") ; 


} 
Output 


The return code from cvtcs is 0 
The return code from cvtsc is 0 
Conversion successful 
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Convert Time (CVTT) 


Format 
#include <QSYSINC/MIH/MIDTTM> 


void cvtt (_SPCPTR result _time, 
_SPCPTRCN source_time, 
_INST_Template_Tl *inst_t); 


Description 

The cvit function converts the time from one format to another format. The time 
specified in source_time is converted to another external or internal presentation 
and placed in result_time. 


Parameters 
result_time (input/output) 
Pointer to the location to receive the converted time. 


source_time (input) 
Pointer to the source time. 


inst_t (input) 
Pointer to the instruction template which defines the data definitional attributes 
for result_time and source_time. 


Notes on Usage 
¢ The builtin function CVTT also provides access to the MI instruction. 


e Amacro version is available. 
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Example 
This example illustrates the use of the cvtt function. 
/ dese Se eh es ssp es eee cose s ee see tee e eee cee ee eee ees ee eee */ 
/* x*/ 
/* Example Group: Date/Time/Timestamp <QSYSINC/MIH/MIDTTM> */ 
/* */ 
/* Function: cvtt (Convert Time) */ 
/* */ 
/* Description: This example uses 'cvtt' to convert the time */ 
/* from ISO time to USA time. */ 
/* x/ 
[Resse esl see Stet eee eee ce ees se eee eee ee eee ee eet eee eee */ 
#include <QSYSINC/MIH/MIDTTM> 
#include <string.h> 
#include <stdio.h> 
#include <stdlib.h> 
#include <stddef.h> 
int main(void) { 
_INST_Template_T1l *inst_tl; 
_DDAT_T «ddat_tl, *ddat_t2; 
int DDAT_Length, Calendar Offset; 
int DDAT Size, Template Size; 
int DDAT_Offset1, DDAT_Offset2; 
char result_t[9]; 
char source t[9] = "11.05.30"; 
DDAT_Length = sizeof(_DDAT_T) + 
2*(sizeof(_Calendar_Table T)) - sizeof(short) + 
sizeof(_Era_ Table T) - 1; 
Calendar Offset = offsetof(_DDAT T, Tables) + 
sizeof(_Era_ Table 71); 
DDAT_Size = 2*DDAT_Length + 
2*(sizeof(int)) + /* DDAT Offset */ 
10 + /* reserved4 = */ 
sizeof(short) + /* Num_DDATs  */ 
sizeof (int); /* DDAT Size */ 
Template Size = 2*DDAT_Length + offsetof(_INST_Template_Tl, DDAT) + 
sizeof(int); /* ddat offset */ 
DDAT_Offsetl = (offsetof(_INST Template_T1, DDAT) - 
offsetof(_INST Template _T1, DDAT Size)) + 
sizeof(int); /* DDAT2 offset */ 
DDAT_Offset2 = (offsetof(_INST_ Template_T1, DDAT) - 
offsetof(_INST Template _T1, DDAT Size)) + 
DDAT_ Length + sizeof(int); /* DDAT2 offset */ 
inst_tl = (_INST Template Tl *)malloc(Template Size); 
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/* Fill in Instruction Template */ 
memset(inst_tl, '\O', sizeof(_INST Template T1)); 
inst_tl->Template Size = Template Size; 
inst_t1->DDAT_1 = 1; 

inst_t1->DDAT_2 = 2; 

inst_t1l->Length_1 = 8; 

inst_tl->Length_2 = 8; 

inst_t1->DDAT_Size = DDAT_Size; 
inst_t1l->Num_DDATs Suds 

inst_t1->DDAT_ Offset [0] = DDAT_Offset1; 
*(inst_t1->DDAT_Offset + 1)= DDAT_Offset2; 

ddat_tl = (_DDAT_T *)&(inst_t1->DDAT Offset + 2); 
ddat_t2 = (_DDATT *)((char *)ddat_t1 + DDAT Length); 
/* Fill in DDAT1 */ 
ddat_t1->DDAT_Length = DDAT_Length; 
ddat_t1->Format_Code = _USA_TIME; 
ddat_t1->Hour_Zone = 24; 

ddat_t1->Min_Zone = 60; 

ddat_t1->Calendar_Offset = Calendar Offset; 

/* Fill in DDAT2 */ 


ddat_t2->DDAT_Length = DDAT_Length; 
ddat_t2->Format_Code = _ISO_TIME; 
ddat_t2->Hour_Zone = 24; 
ddat_t2->Min_Zone = 60; 


ddat_t2->Calendar_Offset = Calendar Offset; 
cvtt(result_t, source t, inst_t1); 
result_t[8] = '\0'; 


printf("The converted time is %s\n", result_t); 


} 


Output 
The converted time is 11:05 AM 


cvtts 


Convert Timestamp (CVTTS) 


Format 
#include <QSYSINC/MIH/CVTTS> 


void cvtts (_SPCPTR result_timestamp, 
_SPCPTRCN source_timestamp, 
_INST_Template_Tl *inst_t); 


Description 

The cvtts function converts the timestamp from one format to another. The 
timestamp specified in source_timestamp is converted to another external or 
internal presentation and placed in result_timestamp. 


Parameters 
result_timestamp (input/output) 
Pointer to the location to receive the converted timestamp. 


source_timestamp (input) 
Pointer to the source timestamp. 


inst_t (input) 
Pointer to the instruction template which defines the data definitional attributes 
for result_timestamp. and source_timestamp. 


Notes on Usage 
e The builtin function CVTTS also provides access to the MI instruction. 


e Amacro version is available. 
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Example 

This example illustrates the use of the cvtts function. 

/eoesoe sos eset ese eee tse eee eee shee ete eee eee cee te 
/* 

/* Example Group: Date/Time/Timestamp <QSYSINC/MIH/MIDTTM> 

/* 

/* Function: cvtts (Convert Timestamp) 

/* 

/* Description: This example uses 'cvtts' to convert the time- 

/* stamp from *YYYYMMDDhhmmss timestamp format to 

/* SAA timestamp format. 

/* 

Jeeassnsese sas see ese Soest see Sh ce pee eee ete tee eee eee eee esate 


#include <QSYSINC/MIH/MIDTTM> 
#include <string.h> 
#include <stdio.h> 
#include <stdlib.h> 
#include <stddef.h> 


/* Internal format for start of Gregorian timeline: January 1, 0001 */ 


#define GREGORIAN TIMELINE START 1721424 


/* Internal format for end of Gregorian timeline: January 1, 10000 


#define GREGORIAN TIMELINE END 5373485 
int main(void) { 


_INST_Template_T1l *inst_tl; 

_DDAT_T *ddat_tl, *ddat_t2; 
_Era_Table T *xera_tl, *era_t2; 
_Calendar_Table T *cal_tl, *cal_t2; 


int DDAT_Length, Calendar Offset; 

int DDAT Size, Template Size; 

int DDAT_Offset1, DDAT_Offset2; 

char result_ts[27]; 

char source _ts[15] = "19930117110530"; 


DDAT_Length = sizeof(_DDAT_T) + 


2*(sizeof(_Calendar_Table T)) - sizeof(short) + 


sizeof(_Era_ Table T) - 1; 


Calendar Offset = offsetof(_DDAT T, Tables) + 
sizeof(_Era_ Table T); 


DDAT_Size = 2*DDAT_Length + 
2*(sizeof(int)) + /* DDAT Offset 
10 + /* reserved4 
sizeof(short) + /* Num_DDATs 
sizeof (int); /* DDAT Size 


*/ 
*/ 
*/ 
*/ 


Template Size = 2*DDAT_Length + offsetof(_INST_Template_Tl, DDAT) + 


sizeof(int); /* ddat offset */ 


DDAT_Offsetl = (offsetof(_INST Template_T1, DDAT) 


cvtts 


offsetof(_INST Template _T1, DDAT Size)) + 
sizeof(int); /* DDAT2 offset */ 


DDAT_Offset2 = (offsetof(_INST Template_T1, DDAT) - 
offsetof(_INST Template _T1, DDAT Size)) + 
DDAT_ Length + sizeof(int); /* DDAT2 offset */ 
inst_tl = (_INST Template_Tl *)malloc(Template Size); 


/* Fill in Instruction Template */ 


memset(inst_tl, '\O', sizeof(_INST_ Template Tl)); 


inst_tl->Template Size = Template Size; 
inst_t1->DDAT_1 =1; 
inst_t1->DDAT_2 = 2; 
inst_tl->Length_1 = 26; 
inst_tl->Length_2 = 14; 
inst_t1->DDAT_Size = DDAT_Size; 
inst_t1l->Num_DDATs S23 
inst_t1->DDAT_ Offset [0] = DDAT Offset1; 


*(inst_t1->DDAT_Offset + 1)= DDAT_Offset2; 


ddat_tl = (_DDAT_T *)&(inst_t1->DDAT Offset + 2); 


era_tl = (_Era_Table T *)&(ddat_t1->Tables); 

cal_ tl = (Calendar Table T *)((char *)ddat_t1 + Calendar Offset); 
ddat_t2 = (_DDATT *)((char *)ddat_t1 + DDAT Length); 

era_t2 = (_Era_Table_ T *)&(ddat_t2->Tables); 

cal_t2 = (Calendar Table T *)((char *)ddat_t2 + Calendar Offset); 
/* Fill in DDAT1 */ 
ddat_t1->DDAT_Length = DDAT_Length; 

ddat_t1->Format_Code = _SAA_TIMESTAMP; 

ddat_t1->Hour_Zone = 24; 

ddat_t1->Min_Zone = 60; 

ddat_t1->Calendar_Offset = Calendar Offset; 

/* Fill in Era Table for DDAT1 */ 
era_t1->Num_Elems = 1; 


era_tl->Element[0].Origin_Date = GREGORIAN TIMELINE START; 
era_t1->Element[0].Era_Name[0] = 'A'; 
era_t1->Element[0].Era_Name[1] = 'D'; 


/* Fill in Calendar Table for DDAT1 */ 
cal_t1->Num_Elems = 2; 
cal_tl->Element->Effect_Date = GREGORIAN_TIMELINE_START; 
cal_tl->Element->Type = 0x0001; 

memset (cal_t1->Element->reserved, '\0', 10); 
(cal_t1->Element+1)->Effect_Date = GREGORIAN TIMELINE END; 
(cal_t1->Element+1)->Type = 0; 


memset ((cal_t1->Element+1)->reserved, '\O', 10); 


/* Fill in DDAT2 */ 
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ddat_t2->DDAT_Length = DDAT_Length; 
ddat_t2->Format_Code = _YYYYMMDDHHMMSS ; 
ddat_t2->Hour_Zone = 24; 

ddat_t2->Min_Zone = 60; 

ddat_t2->Calendar_Offset = Calendar Offset; 

/* Fill in Era Table for DDAT2 */ 
era_t2->Num_Elems axl 


era_t2->Element[0].Origin_Date = GREGORIAN TIMELINE START; 
era_t2->Element[0].Era_Name[0] = 'A'; 
era_t2->Element[0].Era_Name[1] = 'D'; 


/* Fill in Calendar Table for DDAT2 */ 
cal_t2->Num_Elems = 2; 
cal_t2->Element->Effect_Date = GREGORIAN TIMELINE START; 
cal_t2->Element->Type = 0x0001; 

memset (cal_t2->Element->reserved, '\0', 10); 
(cal_t2->Element+1) ->Effect_Date = GREGORIAN TIMELINE END; 


(cal_t2->Element+1)->Type = 0; 
memset ((cal_t2->Element+1)->reserved, '\O', 10); 


cvtts(result_ts, source ts, inst_tl); 
result_ts[26] = '\0'; 


printf("The converted timestamp is %s\n", result_ts); 


} 


Output 
The converted timestamp is 1996-12-17-11.05.30.000000 
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Copy Bytes Left-Adjusted (CPYBLA) 


Format 
#include <QSYSINC/MIH/CPYBLA> 


void cpybla (_SPCPTR receiver, 
_SPCPTRCN source, 
int size); 


Description 
The cpybla function copies size bytes of source to receiver. No padding is done. 


Parameters 
receiver (output) 
Pointer to the receiver. 


source (input) 
Pointer to the source. 


size (input) 
The number of bytes to copy. This must be between 0 and 16 773 104. 


Notes on Usage 
¢ This is a compatibility function to provide the same semantics as the CPYBLA 
MI instruction. 


e Pointers within the source are not preserved by the operation. 
e Behavior is undefined if copying takes place between overlapping locations. 


¢ The builtin CPYBYTES also provides access to an equivalent MI instruction. 
This builtin can only be used to copy non-pointer data. 


Exceptions 
If any of the input parameters are not valid, an MCH3601 or MCHO601 may be 
signalled. 


Other exceptions possible from this function are: 


MCH0602 - Boundary alignment 

MCH0801 - Parameter Reference Violation 
MCH3402 - Object Destroyed 

MCH3602 - Pointer Type Invalid 

MCH6801 - Object Domain Violation 
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Example 
This example illustrates the use of the cpybla function. 


/* Example Group: Computation and Branching QSYSINC/MIH/CPYBLA> 
/* Function: cpybla (Copy Bytes Left-Adjusted) 


/* Description: This example uses 'cpybla' to copy the source 
/* string to the receiver. 


#include <QSYSINC/MIH/CPYBLA> 
#include <string.h> 
#include <stdio.h> 


int main(void) { 


char receiver[] = "XXXXXXXXXXXXXX"5 
char source[] = "Good Day"; 


cpybla(receiver, source, strlen(source)); 
printf("The receiver string is %s\n", receiver); 


} 


Output 
The receiver string is Good DayXXXXXX 


cpyblap 


Copy Bytes Left-Adjusted with Pad (CPYBLAP) 


Format 
#include <QSYSINC/MIH/CPYBLAP> 


void cpyblap (_SPCPTR receiver, 
int revr_size, 
_SPCPTRCN source, 
int src_size, 
char pad); 


Description 

The cpyblap function copies bytes from source to receiver. If source is shorter than 
receiver, then src_size bytes from source are copied to receiver, and each excess 
byte of receiver is assigned the value of pad. If source is longer than receiver, then 
the leftmost bytes of source (equal in length to revr_src) are copied to receiver. 


Parameters 
receiver (input/output) 
Pointer to the receiver. 


revr_size (input) 
The length of the receiver. 


source (input) 
Pointer to the source. 


src_size (input) 
The length of the source. The length must be between 0 and 16 773 104. 


pad (input) 
The pad character. 


Notes on Usage 
¢ This is a compatibility function to provide the same semantics as the CPYBLAP 
MI instruction. 


e If revr_size is <0, no action is taken. 
e If src_size is <0, all bytes of receiver are set to the pad character. 
e Behavior is undefined if copying takes place between overlapping locations. 


e Pointers within source are not preserved. 


Exceptions 
If any of the input parameters are not valid, an MCH3601 or MCHO601 may be 
signalled. 


Other exceptions possible from this function are: 


MCH0602 - Boundary alignment 

MCH0801 - Parameter Reference Violation 
MCH3402 - Object Destroyed 

MCH3602 - Pointer Type Invalid 

MCH6801 - Object Domain Violation 
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Example 

This example illustrates the use of the cpyblap function. 

/eoesoe sos oeet eset apse eet oe eee eee eee eee eos 
/* 

/* Example Group: Computation and Branching <QSYSINC/MIH/CPYBLAP> 
/* 

/* Function: cpyblap (Copy Bytes Left-Adjusted with Pad) 

/* 

/* Description: This example uses 'cpyblap' to copy the source 

/* string to the receiver with padding in the excess 
/* receiver bytes. 

/* 

Jeeassnsese sas see eee Sesh e ee eb oe ee eee eee eee ee eee eal 


#include <QSYSINC/MIH/CPYBLAP> 
#include <string.h> 
#include <stdio.h> 


int main(void) { 


char 
char 


receiver[] = "XXXXXXXXXXXXXXX"5 
source[] = "Good Day"; 


cpyblap(receiver, strlen(receiver), source, strlen(source), '.'); 
printf("The receiver string is %s\n", receiver); 


} 
Output 


The receiver string is Good Day....... 


cpyhexnn 


Copy Hex Digit Numeric to Numeric (CPYHEXNN) 


Format 
#include <QSYSINC/MIH/CPYHEXNN> 


char cpyhexnn (char *dest, char source); 


Description 

The cpyhexnn function copies the numeric hexadecimal digit value (rightmost 4 
bits) of the byte referred to by source to the numeric hexadecimal digit value (right- 
most 4 bits) of the leftmost byte referred to by dest. The function returns a copy of 
the modified byte. 


Parameters 
dest (input/output) 
Pointer to the location whose leftmost byte will be modified. 


source (input) 
The source byte. 


Notes on Usage 
e This is a compatibility function to provide the same semantics as the 
CPYHEXNN MI instruction. 


Exceptions 
If dest does not point to a valid storage location, an MCH3601 will be signalled. 
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Example 

This example illustrates the use of the cpyhexnn function. 

/eoesoe sos oeet ese eee see eet oe sce che eee ee eee eee eee */ 
/* */ 
/* Example Group: Computation and Branching <QSYSINC/MIH/CPYHEXNN> */ 
/* */ 
/* Function: cpyhexnn (Copy Hex Digit Numeric to Numeric) */ 
/* */ 
/* Description: This example uses 'cpyhexnn' to copy the */ 
/* numeric hexadecimal digit (rightmost 4 bits) of */ 
/* the source to the numeric hexadecimal digit */ 
/* (rightmost 4 bits) of the leftmost byte of the */ 
/* destination. */ 
/* */ 
[xeose onsets eee cose eee eee eee eee eee a ee ee ese ees */ 


#include <QSYSINC/MIH/CPYHEXNN> 
#include <stdio.h> 


int main(void) { 


char hex_dest[6] = "2A5F6"; /* in hex: Oxf2 Oxcl Oxf5 Oxc6 Oxf6*/ 
char hex_source = Oxf3, h; 


h = cpyhexnn(hex_dest, hex_source); 


printf("The return byte is %x\n", h); 
printf("The leftmost byte of destination string is %x\n", *hex_dest); 


} 


Output 
The return byte is f3 
The leftmost byte of destination string is f3 


cpyhexnz 


Copy Hex Digit Numeric to Zone (CPYHEXNZ) 


Format 
#include <QSYSINC/MIH/CPYHEXNZ> 


char cpyhexnz (char «dest, char source); 


Description 

The cpyhexnz function copies the numeric hexadecimal digit value (rightmost 4 bits) 
of the byte referred to by source to the zone hexadecimal digit value (leftmost 4 
bits) of the leftmost byte referred to by dest. The function returns a copy of the 
modified byte. 


Parameters 
dest (input/output) 
Pointer to the location whose leftmost byte will be modified. 


source (input) 
The source byte. 


Notes on Usage 
e This is a compatibility function to provide the same semantics as the 
CPYHEXNZ MI instruction. 


Exceptions 
If dest does not point to a valid storage location, an MCH3601 will be signalled. 


Machine Interface Library Functions 75 


cpyhexnz 


76 = Ml Library Reference 


Example 
This example illustrates the use of the cpyhexnz function. 


/* Example Group: Computation and Branching <QSYSINC/MIH/CPYHEXNZ> 


/* 

/* Function: cpyhexnz (Copy Hex Digit Numeric to Zone) 

/* 

/* Description: This example uses 'cpyhexnz' to copy the 

/* numeric hexadecimal digit (rightmost 4 bits) of 

/* the source to the zone hexadecimal digit 

/* (leftmost 4 bits) of the leftmost byte of the 

/* destination. 

/* 

[xeose onsets oee cose eee eee eee eee eee se a ee ee ese ees 


#include <QSYSINC/MIH/CPYHEXNZ> 
#include <stdio.h> 


int main(void) { 


char hex_dest[6] = "2A5F6"; /* in hex: Oxf2 Oxcl Oxf5 Oxc6 Oxf6 */ 
char hex_source = 0xf3, h; 


h = cpyhexnz(hex_dest, hex_source); 


printf("The return byte is %x\n", h); 
printf("The leftmost byte of destination string is %x\n", *hex_dest); 


} 


Output 
The return byte is 32 
The leftmost byte of destination string is 32 


cpyhexzn 


Copy Hex Digit Zone to Numeric (CPYHEXZN) 


Format 
#include <QSYSINC/MIH/CPYHEXZN> 


char cpyhexzn (char «dest, char source); 


Description 

The cpyhexzn function copies the zone hexadecimal digit value (leftmost 4 bits) of 
the byte referred to by source to the numeric hexadecimal digit value (rightmost 4 
bits) of the leftmost byte referred to by dest. The function returns a copy of the 
modified byte. 


Parameters 
dest (input/output) 
Pointer to the location whose leftmost byte will be modified. 


source (input) 
The source byte. 


Notes on Usage 
e This is a compatibility function to provide the same semantics as the 
CPYHEXZN MI instruction. 


Exceptions 
If dest does not point to a valid storage location, an MCH3601 will be signalled. 
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Example 
This example illustrates the use of the cpyhexzn function. 


/* Example Group: Computation and Branching <QSYSINC/MIH/CPYHEXZN> 


/* 

/* Function: cpyhexzn (Copy Hex Digit Zone to Numeric) 

/* 

/* Description: This example uses 'cpyhexzn' to copy the zone 

/* hexadecimal digit (leftmost 4 bits) of the source 
/* to the numeric hexadecimal digit (rightmost 4 

/* bits) of the leftmost byte of the destination. 

/* 

/#eoe eee oe Sees eee cee te eee ee eee eee ee eo ee ee eee ees 


#include <QSYSINC/MIH/CPYHEXZN> 
#include <stdio.h> 


int main(void) { 


char hex_dest[6] = "2A5F6"; /* in hex: Oxf2 Oxcl Oxf5 Oxc6 Oxf6 */ 
char hex_source = 0xf3, h; 


h = cpyhexzn(hex_dest, hex_source); 


printf("The return byte is %x\n", h); 
printf("The leftmost byte of destination string is %x\n", *hex_dest); 


} 


Output 
The return byte is ff 
The leftmost byte of destination string is ff 


cpyhexzz 


Copy Hex Digit Zone to Zone (CPYHEXZZ) 


Format 
#include <CPYHEXZZ> 


char cpyhexzz (char «dest, char source); 


Description 

The cpyhexzz function copies the zone hexadecimal digit value (leftmost 4 bits) of 
the byte referred to by source to the zone hexadecimal digit value (leftmost 4 bits) 
of the leftmost byte referred to by dest. The function returns a copy of the modified 
byte. 


Parameters 
dest (input/output) 
Pointer to the location whose leftmost byte will be modified. 


source (input) 
The source byte. 


Notes on Usage 
e This is a compatibility function to provide the same semantics as the 
CPYHEXZZ MI instruction. 


Exceptions 
If dest does not point to a valid storage location, an MCH3601 will be signalled. 
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Example 
This example illustrates the use of the cpyhexzz function. 


/* Example Group: Computation and Branching <QSYSINC/MIH/CPYHEXZZ> 


/* 

/* Function: cpyhexzz (Copy Hex Digit Zone to Zone) 

/* 

/* Description: This example uses 'cpyhexzz' to copy the zone 

/* hexadecimal digit (leftmost 4 bits) of the source 
/* to the zone hexadecimal digit (leftmost 4 bits) 

/* of the leftmost byte of the destination. 

/* 

/eeoe eee pee ee see ects ee eee ee eee eee eee eee eo ee es eee ees 


#include <QSYSINC/MIH/CPYHEXZZ> 
#include <stdio.h> 


int main(void) { 


char hex_dest[6] = "2A5F6"; /* in hex: Oxf2 Oxcl Oxf5 Oxc6 Oxf6 */ 
char hex_source = 0xf3, h; 


h = cpyhexzz(hex_dest, hex_source); 


printf("The return byte is %x\n", h); 
printf("The leftmost byte of destination string is %x\n", *hex_dest); 


} 


Output 
The return byte is f2 
The leftmost byte of destination string is f2 


cpynv 


Copy Numeric Value (CPYNV) 


Format 
#include <QSYSINC/MIH/CPYNV> 


_SPCPTR cpynv (_NUM_Descr_T rcvr_descr, 
_SPCPTR receiver, 
_NUM_Descr_T src_descr, 
_SPCPTRCN source); 


Description 
The cpynv function copies the numeric value of source to receiver, with the appro- 
priate conversions. The function returns a pointer to the receiver. 


Parameters 
revr_descr (input) 
The receiver descriptor. Must be prepared using the NUM_DESCR macro. 


receiver (input/output) 
Pointer to the receiver location where the result will be placed. 


src_descr (input) 
The source descriptor. Must be prepared using the NUM_DESCR macro. 


source (input) 
Pointer to the source value. 


Notes on Usage 
e If necessary, source is converted to the same type as receiver before being 
copied. 


e The builtin function LBCPYNV (Late-bound Copy Numeric Value) provides 
access to the MI instruction. 


e The builtin function CPYNV also provides access to the equivalent MI instruc- 
tion. When using the _CPYNV instruction, you must specify literal constants for 
the receiver and source descriptor values. _CPYNV is considerably faster than 
_LBCPYNV for the following conversions: 


zoned to packed, float, signed integer, or unsigned integer 
packed to zoned 

signed integer to zoned 

unsigned integer to zoned 
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Example 

This example illustrates the use of the cpynv function. 

/eoesoe sos eset ese eal see eet oe eos ee eee eee eee eee */ 
/* */ 
/* Example Group: Computation and Branching <QSYSINC/MIH/CPYNV> ~ */ 
/* */ 
/* Function: cpynv (Copy Numeric Value) */ 
/* */ 
/* Description: This example uses 'cpynv' to convert a long */ 
/* double number to zoned decimal. */ 
/* */ 
/eeessnsese cos see ese Sessa ese ee est ee See ole ee se ee eee eset */ 


#include <QSYSINC/MIH/CPYNV> 
#include <stdio.h> 


void convert_double to _zone(unsigned char *, int, int, double); 
int main(void) { 


char zoned_output[15]; 
double float_input = 36584.89; 


convert_double_to_zone(zoned_output, 
15, 
55 
float_input) ; 


printf("The zoned decimal number ZND(15,5) is %.15s\n", zoned output); 
} 


void convert_double to _zone(unsigned char *znd, int digits, int fraction, 
double dbl) 
{ 
cpynv(NUM_DESCR(_T_ ZONED, digits, fraction), znd, 
NUM_DESCR(_T_FLOAT, 8, 0), &dbl1); 
} 


Output 
The zoned decimal number ZND(15,5) is 000003658489000 


dcpdata 


Decompress Data (DCPDATA) 


Format 
#include <QSYSINC/MIH/DCPDATA> 


int dcpdata (_SPCPTR result, 
int result_length, 
_SPCPTRCN source); 


Description 

The dcpdata function decompresses user data. If the decompressed result is 
longer than the result area (as specified by result_length), the decompression is 
stopped and only result_length bytes are stored. 


The dcpdata function returns the number of bytes in the decompressed result. This 
value is always set to the full length of the result, which may be larger than 
result_length. 


Parameters 
result (input/output) 
Pointer to the result area to receive the decompressed data. 


result_length (input) 
The result area length. 


source (input) 
The data to be decompressed. 


Notes on Usage 
e The length of the source data is not supplied because this 
length is contained within the compressed data. 


¢ The builtin function DCPDATA also provides access to the MI instruction. 
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Example 
This example illustrates the use of the dcpdata function. 


/* Example Group: Computation and Branching <QSYSINC/MIH/DCPDATA> 
/* Function: dcpdata (Decompress Data) 


/* Description: This example uses 'cprdata' and 'dcpdata' to 
/* compress then decompress the input string. 


#include <QSYSINC/MIH/DCPDATA> 
#include <QSYSINC/MIH/CPRDATA> 
#include <string.h> 
#include <stdio.h> 


#define SIZE 50 
int main(void) { 


char cpr_data[SIZE]; 

char dpr_data[SIZE] = "Good Day"; 
int clength; 

int dlength; 


clength = cprdata(cpr_data, SIZE, dpr_data, strlen(dpr_data)); 
printf("The compressed length = %d\n", clength); 


dlength = dcpdata(dpr_data, SIZE, cpr_data); 
printf("The decompressed length = %d\n", dlength); 


if (memcmp(dpr_data, "Good Day", strlen(dpr_data)) != 0) 
printf("Error in decompression\n"); 

else 
printf("Decompression successful \n"); 


} 


Output 

The compressed length = 26 
The decompressed length = 8 
Decompression successful 


decd 


Decrement Date (DECD) 


Format 
#include <QSYSINC/MIH/DECD> 


void decd (_SPCPTR result_date, 
_SPCPTRCN source_date, 
_SPCPTRCN duration, 
_INST_Template_T3 *inst_t); 


Description 

The decd function decrements the date by the date duration. The date specified by 
source_date is decreased by the date duration specified by duration. The resulting 
date from the operation is placed in result_date. 


Parameters 
result_date (input/output) 
Pointer to the location to receive the result. 


source_date (input) 
Pointer to the source date. 


duration (input) 
Pointer to the packed decimal duration. 


inst_t (input) 
Pointer to the instruction template which defines the data definitional attributes 
for result_date, source_date, and duration. 


Notes on Usage 
e The DDATs for result_date and source_date must be identical. 


e The builtin function DECD also provides access to the MI instruction. 


e A macro version is available. 
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Example 

This example illustrates the use of the decd function. 

/eoesse sos oeee ese eee tse eee oes she ee eee eee eee */ 
/* */ 
/* Example Group: Date/Time/Timestamp <QSYSINC/MIH/MIDTTM> */ 
/* */ 
/* Function: decd (Decrement Date) */ 
/* */ 
/* Description: This example uses 'decd' to decrement the date */ 
/* by the date duration. */ 
/* */ 
fees nsese cos eee ese Sees teeta ee est ee eee ose ee see ee ee ee eset */ 


#include <QSYSINC/MIH/MIDTTM> 
#include <string.h> 

#include <stdio.h> 

#include <stdlib.h> 

#include <stddef.h> 

#include <decimal .h> 


/* Internal format for start of Gregorian timeline: January 1, 0001 */ 
#define GREGORIAN TIMELINE START 1721424 


/* Internal format for end of Gregorian timeline: January 1, 10000 */ 
#define GREGORIAN TIMELINE END 5373485 


int main(void) { 


_INST_Template_T3  *inst_t3; 
_DDAT_T *ddat_tl, *ddat_t2; 
_Era_Table T xera_tl; 
_Calendar_Table T *cal_tl; 


int DDAT_Length, Calendar Offset; 
int DDAT_Size, Template Size; 

int DDAT_Offset1, DDAT_Offset2; 
char result_d[11]; 

char source _d[11] = "1993-01-30"; 
decimal (8,0) duration = 00120310D; 


DDAT_Length = sizeof(_DDAT_T) + 
2*(sizeof(_Calendar_ Table T)) - sizeof(short) + 
sizeof(_Era_ Table T) - 1; 


Calendar Offset = offsetof(_DDAT T, Tables) + 
sizeof(_Era_ Table T); 


DDAT_Size = 2*DDAT_Length + 
2*(sizeof(int)) + /* DDAT Offset */ 
10 + /* reserved4 = */ 
sizeof(short) + /* Num_DDATs */ 
sizeof (int); /* DDAT Size */ 


Template Size = 2*DDAT_Length + offsetof(_INST_Template_T3, DDAT) + 
sizeof(int); /* ddat offset */ 


decd 


DDAT Offsetl = (offsetof(_INST Template T3, DDAT) - 
offsetof(_INST Template _T3, DDAT Size)) + 
sizeof(int); /* DDAT2 offset */ 

DDAT Offset2 = (offsetof(_INST Template 13, DDAT) - 
offsetof(_INST Template _T3, DDAT Size)) + 
DDAT_ Length + sizeof(int); /* DDAT2 offset */ 

inst_t3 = (_INST Template T3 *)malloc(Template Size); 


/* Fill in Instruction Template */ 


memset(inst_t3, '\O', sizeof(_INST_ Template T3)); 


inst_t3->Template Size = Template Size; 
inst_t3->DDAT_1 = 1; 
inst_t3->DDAT_2 = 1; 
inst_t3->DDAT_3 E25 
inst_t3->Length_1 = 10; 
inst_t3->Length_2 = 10; 
inst_t3->F_Digits = 0; 
inst_t3->T_Digits = 8; 
inst_t3->Indicators = _OQUT_ADJUST | _IN ADJUST; 
inst_t3->DDAT_Size = DDAT_Size; 
inst_t3->Num_DDATs = 28 
inst_t3->DDAT_ Offset [0] = DDAT Offset1l; 


*(inst_t3->DDAT_Offset + 1)= DDAT_Offset2; 
/* Set table pointers within instruction template */ 


ddat_tl = (_DDAT_T *)&(inst_t3->DDAT Offset + 2); 


era_tl = (_Era_Table T *)&(ddat_t1->Tables) ; 

cal_ tl = (Calendar Table T *)((char *)ddat_t1 + Calendar Offset); 
ddat_t2 = (_DDATT *)((char *)ddat_t1 + DDAT Length); 

/* Fill in DDAT1 */ 
ddat_t1->DDAT_Length = DDAT_Length; 

ddat_t1->Format_Code = _1S0_DATE; 


ddat_t1->Calendar_Offset = Calendar Offset; 


/* Fill in Era Table for DDAT1 x/ 


era_tl->Num_Elems = 1; 

era_tl->Element[0].Origin_Date = GREGORIAN TIMELINE START; 
era_t1->Element[0].Era_Name[0] = 'A'; 
era_t1->Element[0].Era_Name[1] = 'D'; 


/* Fill in Calendar Table for DDAT1 */ 
cal_t1->Num_Elems = 2; 
cal_tl->Element->Effect_Date = GREGORIAN TIMELINE START; 
cal_tl->Element->Type = 0x0001; 


memset (cal_t1l->Element->reserved, '\O', 10); 
(cal_t1->Element+1)->Effect_Date = GREGORIAN TIMELINE_END; 
(cal_t1->Element+1)->Type = 0; 

memset ((cal_t1->Element+1)->reserved, '\O', 10); 
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/* Fill in DDAT 2 


ddat_t2->DDAT_Length = DDAT_Length; 
ddat_t2->Format_Code = _DATE_DUR; 
ddat_t2->Calendar_Offset = Calendar Offset; 


decd(result_d, source _d, &duration, inst_t3); 
result_d[10] = '\0'; 


printf("The resulting date is %s\n", result_d); 


} 


Output 
The resulting date is 1980-10-20 


*/ 


dect 


Decrement Time (DECT) 


Format 
#include <QSYSINC/MIH/DECT> 


void dect (_SPCPTR result_time, 
_SPCPTRCN source_time, 
_SPCPTRCN duration, 
_INST_Template_T3 *inst_t); 


Description 

The dect function decrements the time by the time duration. The time specified by 
source_time is decreased by the time duration specified by duration. The resulting 
time from the operation is placed in result_time. 


Parameters 
result_time (input/output) 
Pointer to the location to receive the result. 


source_time (input) 
Pointer to the source time. 


duration (input) 
Pointer to the packed decimal duration. 


inst_t (input) 
Pointer to the instruction template which defines the data definitional attributes 
for result_time, source_time, and duration. 


Notes on Usage 
e The DDATs for result_time and source_time must be identical. 


e The builtin function DECT also provides access to the MI instruction. 


e Amacro version is available. 
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Example 


This example illustrates the use of the dect function. 


/* Example Group: 
/* Function: 


/* Description: 


Date/Time/Timestamp <QSYSINC/MIH/MIDTTM> 


dect (Decrement Time) 


This example uses 'dect' to decrement the time 


by the time duration. 


#include <QSYSINC/MIH/MIDTTM> 
#include <string.h> 


#include <stdio.h> 


#include <stdlib.h> 
#include <stddef.h> 


#include <decimal .h> 


int main(void) { 


_INST_Template_T3 


_DDAT_T 


int 
int 
int 
char 


char 
decimal (6,0) 


*inst_t3; 
*ddat_tl, *ddat_t2; 


DDAT_Length, Calendar Offset; 
DDAT_Size, Template Size; 
DDAT_Offset1, DDAT_Offset2; 


result_d[9]; 
source d[9] = "11.05.30"; 
duration = 000205D; 


DDAT_Length = sizeof(_DDAT_T) + 
2*(sizeof(_Calendar_ Table T)) - sizeof(short) + 
sizeof(_Era_ Table T) - 1; 


Calendar_Offset 


DDAT_Size 


Template _Size 


DDAT_Offset1 


DDAT_Offset2 


offsetof(_DDAT T, Tables) + 
sizeof(_Era_ Table T); 


2*DDAT_Length + 
2*(sizeof(int)) + /* DDAT Offset */ 


10 + /* reserved4 = */ 
sizeof(short) + /* Num_DDATs = */ 
sizeof (int); /* DDAT Size */ 


2*DDAT_Length + offsetof(_INST Template_T3, DDAT) + 


sizeof(int); /* ddat offset */ 


(offsetof(_INST Template 13, DDAT) - 
offsetof(_INST Template _T3, DDAT Size)) + 
sizeof(int); /* DDAT2 offset */ 


(offsetof(_INST Template 13, DDAT) - 
offsetof(_INST Template _T3, DDAT Size)) + 
DDAT_ Length + sizeof(int); /* DDAT2 offset */ 


inst_t3 


/* Fill in Instruction Template 


= (_INST_Template_T3 *)malloc(Template Size); 


*/ 


memset(inst_t3, '\O', sizeof(_INST Template T3)); 


inst_t3->Template Size 
inst_t3->DDAT_1 
inst_t3->DDAT_2 
inst_t3->DDAT_3 
inst_t3->Length_1 
inst_t3->Length_2 
inst_t3->F_Digits 
inst_t3->T_Digits 
inst_t3->Indicators 
inst_t3->DDAT_Size 
inst_t3->Num_DDATs 
inst_t3->DDAT_Offset [0] 
*(inst_t3->DDAT_Offset + 1) 


ddat_tl 
ddat_t2 


/* Fill in DDAT1 


ddat_t1->DDAT_Length 
ddat_t1->Format_Code 
ddat_t1->Hour_Zone 
ddat_t1->Min_Zone 
ddat_t1->Calendar_Offset 


/* Fill in DDAT2 


ddat_t2->DDAT_Length 
ddat_t2->Format_Code 
ddat_t2->Hour_Zone 
ddat_t2->Min_Zone 
ddat_t2->Calendar_Offset 


dect(result_d, source d, 


result_d[8] ‘'\O'; 


Template Size; 


> 
> 


_NO_ADJUST_OR_TOLERATE; 
DDAT_Size; 

23 

DDAT_Offset1; 
DDAT_Offset2; 


(_DDAT_T *)&(inst_t3->DDAT Offset + 2); 
(_DDAT_T *)((char *)ddat_t1 + DDAT Length); 


*/ 


DDAT_Length; 


_1SO_TIME; 


60; 
Calendar Offset; 


*/ 


DDAT_Length; 
_TIME_DUR; 
0; 

0; 
Calendar_Offset; 


&duration, inst_t3); 


printf("The resulting time is %s\n", result_d); 


} 


Output 


The resulting time is 11.03.25 
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Decrement Timestamp (DECTS) 
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Format 
#include <QSYSINC/MIH/MIDTTM> 


void dects (_SPCPTR result_timestamp, 
_SPCPTRCN source_timestamp, 
_SPCPTRCN duration, 
_INST_Template_T3 *inst_t); 


Description 

The dects function decrements the timestamp by the timestamp duration. The 
timestamp specified by source_timestamp is decreased by the date, time, or 
timestamp duration specified by duration. The resulting timestamp from the opera- 
tion is placed in result_timestamp. 


Parameters 
result_timestamp (input/output) 
Pointer to the location to receive the result. 


source_timestamp (input) 
Pointer to the source timestamp. 


duration (input) 
Pointer to the packed decimal duration. 


inst_t (input) 
Pointer to the instruction template which defines the data definitional attributes 
for result_timestamp, source_timestamp, and duration. 


Notes on Usage 
e The DDATs for result_timestamp and source_timestamp must be identical. 
e The builtin function DECTS also provides access to the MI instruction. 


e Amacro version is available. 


dects 


Example 

This example illustrates the use of the dects function. 

/ eeSe Se eh es ssp es ee b eco ees ee settee cee eee eee esse ee eee */ 
/* */ 
/* Example Group: Date/Time/Timestamp <QSYSINC/MIH/MIDTTM> */ 
/* */ 
/* Function: dects (Decrement Timestamp) */ 
/* */ 
/* Description: This example uses ‘dects' to decrement the time- */ 
/* stamp by the timestamp duration. */ 
/* */ 
/xReesst ssl seesset eee ese ee se see esl ees eee eee sees eee eet eee eee */ 
#include <QSYSINC/MIH/MIDTTM> 

#include <stdio.h> 

#include <stdlib.h> 

#include <stddef.h> 

#include <string.h> 

#include <decimal.h> 


/* Internal format for start of Gregorian timeline: January 1, 0001 */ 
#define GREGORIAN TIMELINE START 1721424 


/* Internal format for end of Gregorian timeline: January 1, 10000 +*/ 
#define GREGORIAN TIMELINE END 5373485 


int main(void) { 


_INST_Template_T3  *inst_t3; 


_DDAT_T 


*ddat_tl, *ddat_t2; 


_Era_Table_T xera_tl; 
_Calendar_Table T *cal_tl; 


int DDAT_Length, Calendar Offset; 

int DDAT_Size, Template Size; 

int DDAT_Offset1, DDAT_Offset2; 

char result_d[27]; 

char source_d[27] = "1993-01-17-11.05.30.000000"; 
decimal (20,6) duration = 00000203012005.000000D; 


DDAT_Length = sizeof(_DDAT_T) + 


2*(sizeof(_Calendar_Table T)) - sizeof(short) + 
sizeof(_Era_ Table T) - 1; 


Calendar Offset = offsetof(_DDAT T, Tables) + 


sizeof(_Era_ Table T); 


DDAT_Size = 2*DDAT_Length + 
2*(sizeof(int)) + /* DDAT Offset */ 
10 + /* reserved4 = */ 
sizeof(short) + /* Num_DDATs */ 
sizeof (int); /* DDAT Size */ 
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Template Size = 


DDAT_Offset1 


DDAT_Offset2 


2*DDAT_Length + offsetof(_INST Template_T3, DDAT) + 
sizeof(int); /* ddat offset */ 


= (offsetof(_INST Template 13, DDAT) - 
offsetof(_INST Template _T3, DDAT Size)) + 
sizeof(int); /* DDAT2 offset */ 


= (offsetof(_INST Template 13, DDAT) - 
offsetof(_INST Template _T3, DDAT Size)) + 
DDAT_ Length + sizeof(int); /* DDAT2 offset */ 


inst_t3 = (_INST Template T3 *)malloc(Template Size); 
/* Fill in Instruction Template */ 
memset(inst_t3, '\O', sizeof(_INST_ Template T3)); 
inst_t3->Template Size = Template Size; 
inst_t3->DDAT_1 = 1; 

inst_t3->DDAT 2 = 1; 

inst_t3->DDAT_3 223 

inst_t3->Length_1 = 26; 

inst_t3->Length_2 = 26; 

inst_t3->F_Digits = 6; 

inst_t3->T_Digits = 20; 

inst_t3->Indicators = _OUT_ADJUST | _IN ADJUST; 
inst_t3->DDAT_ Size = DDAT Size; 
inst_t3->Num_DDATs S25 

inst_t3->DDAT_ Offset [0] = DDAT Offset1; 
*(inst_t3->DDAT_Offset + 1)= DDAT_Offset2; 

/* Set table pointers within instruction template */ 


ddat_tl 
era_tl 
cal_tl 
ddat_t2 


/* Fill in DDAT1 


ddat_t1->DDAT_Length = 
ddat_t1->Format_Code = 
ddat_t1->Hour_Zone 7 
ddat_t1->Min_Zone = 
ddat_t1->Calendar_Offset = 


/* Fill in Era Table for 


era_t1->Num_Elems 


(_DDAT_T *)&(inst_t3->DDAT Offset + 2); 

(_Era_Table T *)&(ddat_t1->Tables); 

(Calendar Table T *)((char *)ddat_t1 + Calendar Offset); 
(_DDAT_T *)((char *)ddat_t1 + DDAT Length); 


*/ 


DDAT_Length; 
_SAA_TIMESTAMP ; 
24; 

60; 
Calendar_Offset; 


DDAT1 */ 


= 1; 


era_t1->Element[0].Origin Date = 


era_t1->Element[0].Era_Name[0] 
era_t1->Element[0].Era_Name[1] 


/* Fill in Calendar Table for DDAT1 


cal_t1->Num_Elems 
cal_tl->Element->Effect_Date = 


GREGORIAN TIMELINE START; 
"A's 

'D's 

*/ 


= 2: 


GREGORIAN TIMELINE START; 


dects 


cal_tl->Element->Type = 0x0001; 

memset (cal_t1->Element->reserved, '\0', 10); 
(cal_t1->Element+1)->Effect_Date = GREGORIAN TIMELINE_END; 
(cal_t1->Element+1)->Type = 0; 

memset ((cal_t1->Element+1)->reserved, '\O', 10); 


/* Fill in DDAT 2 */ 
ddat_t2->DDAT_Length = DDAT_Length; 
ddat_t2->Format_Code = _TIMESTAMP_DUR; 
ddat_t2->Hour_Zone = 0Q; 

ddat_t2->Min_Zone = 0; 


ddat_t2->Calendar_Offset = Calendar Offset; 
dects(result_d, source _d, &duration, inst_t3); 


result_d[26] = '\O'; 
printf("The resulting timestamp is %s\n", result_d); 


} 


Output 
The resulting timestamp is 1996-12-14-09.45.25.000000 
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Dequeue (DEQ) 


Format 
#include <QSYSINC/MIH/DEQ> 


void deq (_DEQ Msg Prefix_T *msg_prefix, 
_SPCPTR message, 
_SYSPTR queue); 


Description 

The deq function retrieves a queue message based on the queue type (FIFO, 
LIFO, or keyed) specified during the queue's creation. If a message is not found 
that satisfies the dequeue selection criteria, the process waits until a message 
arrives to satisfy the dequeue or until the dequeue wait time-out expires. 


Parameters 

msg_ prefix (input/output) 
Pointer to the message prefix template. This contains the criteria for message 
selection. 


message (output) 
Pointer to the location to receive the message text. 


queue (input) 
Pointer to the queue from which the message is to be dequeued. 


Notes on Usage 
¢ The builtin function DEQWAIT also provides access to the MI instruction. 


Example 

This example illustrates the use of the deq function. 

/eoeeSo nS sones- Secs f es eee ess ose ee see te Suet ecneh seo bese esse oe ee */ 
/* */ 
/* Example Group: User Queues <QSYSINC/MIH/DEQ> */ 
/* */ 
/* Function: deq (dequeue) */ 
/* */ 
/* Description: This example will dequeue the next message from */ 
/* the user queue and output it to the screen. If */ 
/* there are no entries are on the queue, this */ 
/* program will wait indefinitely until one appears. */ 
/* */ 
/eoesresos sents soso cess eee ce seh e eee ee eee eee ee ete */ 


#include <QSYSINC/MIH/DEQ> 
#include <QSYSINC/MIH/RSLVSP> 
#include <stdio.h> 


/* Template used for setting */ 
/* options for the dequeue. */ 
_DEQ Msg Prefix_T message prefix; /* Also used as the receiver */ 
/* for the dequeued message. */ 
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_SYSPTR queue_ptr; /* Pointer to the user queue. 


char message _text[ 75 ]; /* Buffer for dequeued message. 


int main(void) { 


/* Get a pointer to the *USRQ. 
queue_ptr = rslvsp( Usrq, "MYUSRQ", "MYLIB", AUTH ALL ); 


message prefix.Wait_Forever = 1; /* Wait indefinitely until an 
/* entry appears on the queue. 


/* Dequeue the next message from the user queue and store it in the 
/* 'message text' buffer. If the queue is empty, this program will 
/* be suspended until an entry appears (by some other job running a 
/* a program that enqueues an entry on the queue). 


deq( &message prefix, message text, queue ptr ); 


/* Display the received message 
/* to the screen. 


printf("Each entry/message is %d bytes long.\n", 
message _prefix.Msg Size ); 


printf("The following was received from the User Queue. \n"); 
printf("> %.75s \n\n", message text ); 


} 


Output 

Each entry/message is 75 bytes long. 

The following was received from the User Queue. 
> This is the first message being entered. 
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Dequeue Message with Indicator (DEQI) 


Format 
#include <QSYISNC/MIH/DEQ> 


int deqi (_DEQ Msg Prefix_T *msg_prefix, 
_SPCPTR message, 
_SYSPTR queue); 


Description 

The deqi function retrieves a queue message based on the queue type (FIFO, 
LIFO, or keyed) specified during the queue's creation. If a message satisfying the 
dequeue selection criteria is not available, the function will return immediately with 
the return code set as indicated below. The process is not placed in a wait state. 


Parameters 

msg_ prefix (input/output) 
Pointer to the message prefix template. This contains the criteria for message 
selection. 


message (output) 
Pointer to the location to receive the message text. 


queue (input) 
Pointer to the queue from which the message is to be dequeued. 


Notes on Usage 
e The builtin function _DEQI also provides access to the MI instruction. 


Return Code 
Values returned by the function degi are: 


Value Meaning 

1 Message dequeued 

0 No message meeting dequeue criteria on the queue 
Example 

This example illustrates the use of the deqi function. 

Jeece ese o state e ese ese eee ee ote ee eee eb eee ee eee eee eee */ 
/* */ 
/* Example Group: User Queues <QSYSINC/MIH/DEQ> */ 
/* */ 
/* Function: deqi (dequeue and set indicator) */ 
/* */ 
/* Description: This example dequeues the next message from the */ 
/* user queue and displays it to the screen. If */ 
/* there are no entries, this program continues and */ 
/* the return code (indicator) from 'deqi' will */ 
/* indicate whether or not there was anything on the */ 
/* queue to be dequeued. */ 
/* */ 
feeossnssse ses sete ees see sce eee ee coe eee est eset eee eee ee eee eects */ 
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#include <QSYSINC/MIH/DEQ> 
#include <QSYSINC/MIH/RSLVSP> 
#include <stdio.h> 

#include <stdlib.h> 


deqi 


/* Stores information returned */ 
_DEQ Msg Prefix_T message prefix; /* by the 'deqi' function. x/ 
_SYSPTR queue ptr; /* Pointer to the user queue. */ 
char message _text[ 75 ]; /* Buffer for dequeued message.*/ 
int return_code; /* "indicator" returned by deqi*/ 
int main(void) { 
/* Get a pointer to the *USRQ. */ 
queue_ptr = rslvsp( Usrq, "MYUSRQ", "MYLIB", AUTH ALL ); 
[Reeser ee sete see see eee sess se eee eben tee eee Leese */ 
/* The 'deqi' function unlike the 'deq' function will always return */ 
/* right away whether or not an entry was found on the user queue. x/ 
[Reece se cess ses lees st seuss sete su pte shee ent ee pe See se eee cust st */ 
return_code = deqi( &message prefix, message text, queue ptr ); 
if ( return_code == 0 ) { 
printf("The queue was empty. 'deqi' returned 0.\n"); 
exit( 1); 
} 
/* Inform the user of the message */ 


/* that was received from the queue*/ 


printf("'deqi' returned %d indicating a successful dequeue\n", 
return_code ); 


printf("The following was received from the User Queue. \n"); 
printf("> %.75s \n", message text ); 


} 
Output 


‘deqi' returned 1 indicating a successful dequeue 
The following was received from the User Queue. 
> This is the second message being entered. 
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Edit (EDIT) 


Format 
#include <QSYSINC/MIH/EDIT> 


void edit (_SPCPTR receiver, 
unsigned int revr_length, 
_SPCPTRCN source, 
_NUM_Descr_T src_descr, 
_SPCPTR mask, 
unsigned int mask_length); 


Description 

The edit function transforms the value of a numeric source from its internal form to 
character form suitable for display at a source/sink device and places the result in 
receiver. There are a number of general editing functions (such as unconditional 
insertion of a mask character string), that can be performed during the transforma- 
tion. 


Parameters 
receiver (input/output) 
Pointer to the location to receive the transformed result. 


revr_length (input) 
The length of the receiver area. This value must be between 1 and 256. 


source (input) 
The source string address. 


src_descr (input) 
The source descriptor. Must be prepared using the NUM_DESCR macro. 


mask (input) 
The mask string address. 


mask_length (input) 
The mask string length. This value must be between 1 and 256. 


Notes on Usage 
e The builtin function LBEDIT (Late-bound Edit) also provides access to the MI 
instruction. 
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Example 

This example illustrates the use of the edit function. 

/ eeee Sees sone s epee cose see see to Se ce ee eee eee see eee */ 
/* */ 
/* Example Group: Computation and Branching <QSYSINC/MIH/EDIT> */ 
/* */ 
/* Function: edit (Edit) */ 
/* */ 
/* Description: This example uses ‘edit' to transform the integer */ 
/* source into character form suitable for display. */ 
/* The edit mask controls the blank padding and */ 
/* the insertion of the appropriate sign. */ 
/* */ 
/xeeeeeesseteese epee eet eee ee eee eee ee ee ee eee */ 


#include <QSYSINC/MIH/EDIT> 
#include <string.h> 
#include <stdio.h> 


#define SIZE 11 
int main(void) { 


char receiver[SIZE+1] ; 

char edit_mask[18] = 
{0x34, Oxbl, 0x40, Ox4e, 0x34, 0x60, 0x34, 
OxB2, OxB2, OxB2, OxB2, OxB2, OxB2, Qxb2, 
O@xB2, OxB2, OxB2, OxB2}; 


unsigned mask_len = sizeof (edit_mask); 
int source = 12652; 


edit(receiver, SIZE, &source, NUM DESCR(_T_UNSIGNED, 4, 0), 
edit_mask, mask_len); 

receiver[SIZE] = '\0'; 

printf("The transformed result is >>%s<<\n", receiver); 


} 


Output 


The transformed result is >> +12652<< 
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Edit Packed Decimal (EDIT_PACKED) 


Format 
#include <QSYSINC/MIH/EDIT> 


void edit_packed (_SPCPTR receiver, 
unsigned int revr_length, 
_SPCPTRCN source, 
unsigned int src_length, 
_SPCPTR mask, 
unsigned int mask_length); 


Description 

The edit_packed function transforms the value of a packed decimal source from its 
internal form to character form suitable for display at a source/sink device and 
places the result in receiver. There are a number of general editing functions (such 
as unconditional insertion of a mask character string), that can be performed during 
the transformation. 


Parameters 
receiver (input/output) 
Pointer to the location to receive the transformed result. 


revr_length (input) 
The length of the receiver area. This value must be between 1 and 256. 


source (input) 
Pointer to the packed decimal source. 


src_length (input) 
The source length. This value must be between 1 and 31. 


mask (input) 
The mask string address. 


mask_length (input) 
The mask length. This value must be between 1 and 256. 


Notes on Usage 
e The builtin function EDITPD also provides access to the MI instruction. 


e This function is faster than edit for a packed decimal source. 
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Example 

This example illustrates the use of the edit_packed decimal function. 

/ eeSe Se eh ess sees eee cess ee see tee eee ee eee eee eee see eee */ 
/* */ 
/* Example Group: Computation and Branching <QSYSINC/MIH/EDIT> */ 
/* */ 
/* Function: edit_packed (Edit Packed Decimal) */ 
/* */ 
/* Description: This example uses 'edit_packed' to transform the */ 
/* packed decimal source into character form */ 
[* suitable for display. The edit mask controls the */ 
/* blank padding and the insertion of the */ 
/* appropriate sign. */ 
/* */ 
Jeeee esses tees sone L eee se ee eee ee eee eee tee ee */ 


#include <QSYSINC/MIH/EDIT> 
#include <decimal.h> 
#include <string.h> 
#include <stdio.h> 


#define SIZE 11 
int main(void) { 


char receiver[SIZE+1] ; 

char edit_mask[18] = 
{0x34, Oxbl, 0x40, Ox4e, 0x34, 0x60, 0x34, 
OxB2, OxB2, OxB2, OxB2, OxB2, OxB2, Qxb2, 
OxB2, OxB2, OxB2, OxB2}; 


unsigned mask_len = sizeof (edit_mask); 
_Decimal(10,0) source = 12652D; 


edit_packed(receiver, SIZE, &source, digitsof(source), edit_mask, 
mask_len); 

receiver[SIZE] = '\0'; 

printf("The transformed result is >>%s<<\n", receiver); 


} 


Output 


The transformed result is >> +12652<< 
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Enqueue (ENQ) 


Format 
#include <QSYSINC/MIH/ENQ> 


void eng (_SYSPTR queue, 
_ENQ Msg Prefix_T «msg prefix, 
_SPCPTR message); 


Description 
The eng function enqueues a message according to the queue type attribute speci- 
fied during the queue's creation. 


Parameters 
queue (input) 
Pointer to the queue to which the message is to be enqueued. 


msg_prefix(input) 
Pointer to the message prefix template. This contains information about the 
message being enqueued. 


message (output) 
Pointer to the message text to be enqueued. 


Notes on Usage 
e The builtin function _ENQ also provides access to the MI instruction. 


Example 

This example illustrates the use of the eng function. 

/#oeseecsse cesses sleet es see eee sce se ees cess eee le ees */ 
/* */ 
/* Example Group: User Queues <QSYSINC/MIH/ENQ> */ 
/* */ 
/* Function: enq (enqueue) x/ 
/* */ 
/* Description: Prompt the user for a string/message that will be */ 
/* enqueued (placed) on a user queue named MYUSRQ in */ 
/* library MYLIB. */ 
/* */ 
feoose eno pete see eee eee be eee eee eee tee te se eee eee bee */ 


#include <QSYSINC/MIH/ENQ> 
#include <QSYSINC/MIH/RSLVSP> 
#include <stdio.h> 


_SYSPTR queue ptr; /* Pointer to the user queue. */ 
_ENQ Msg Prefix_T message prefix; /* Provides description of the */ 
/* message being enqueud. x/ 


/* Stores the input received = */ 
char message _text[ 75 ]; /* from the user which will */ 
/* then be enqueued. */ 
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int main(void) { 


/* Get a pointer to the *USRQ */ 
queue_ptr = rslvsp( _Usrq, "MYUSRQ", "MYLIB", AUTH ALL ); 


/* Prompt the user for the */ 
/* message. */ 


printf("Enter some text you wish to have put on the User Queue:\n"); 
gets( message text ); 


[Resear see tess lets ste ete eee ee ee see ole et */ 
/* Enqueue the user's message onto the user queue. The length of */ 
/* the message is passed in the "prefix" argument (basically a */ 
/* description of the message being enqueued) . */ 
[Roe soesel ses se sete sos se este cate eee eee ease ete e se tee sete ele */ 


message prefix.Msg Len = 75; 
enq( queue_ptr, &message prefix, message text ); 


printf("Your message has been enqueued onto the user queue. \n" ); 


} 


Output 

Enter some text you wish to have put on the User Queue: 
This is the first message being entered. 

Your message has been enqueued onto the user queue. 
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Ensure Object (ENSOBVJ) 


Format 
#include <QSYSINC/MIH/ENSOBJ> 


void ensobj (_SYSPTR object); 


Description 
The ensobj function protects the specified object from volatile storage loss. 


The machine ensures that any changes made to the specified object are recorded 
on nonvolatile storage media. The access state of the object is not changed. 


No action is taken for temporary objects since temporary objects are not preserved 
during machine failure. 


Parameters 
object (input) 
Pointer to the system object to be protected. 


Notes on Usage 
e The builtin function ENSOBJ also provides access to the MI instruction. 
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Example 

This example illustrates the use of the ensobj function. 

/ eeSe Sees espe s eee cose s ee see to eee ope ee eee see eee */ 
/* x/ 
/* Example Group: Resource Management Data(RMD) <QSYSINC/MIH/ENSOBJ>*/ 
/* */ 
/* Function: ensobj (Ensure Object) */ 
/* */ 
/* Description: ‘ensobj' forces objects from volatile (main */ 
/* memory) to non-volatile (disk) storage. This */ 
/* particular example shows how to use ‘ensobj' to */ 
/* "flush" a user queue out to disk to ensure data */ 
/* is not lost in the event of a power loss, etc. */ 
/* x*/ 
Jerse cesses ness se nese e tt Leet ee sb eee eee ee eee cee te eee */ 


#include <QSYSINC/MIH/ENSOBJ> 
#include <QSYSINC/MIH/RSLVSP> 


/* The pointer to the object */ 
_SYSPTR some_object; /* that will be "forced" to */ 
/* auxillary storage (disk). */ 
int main(void) { 
/* Get a pointer to the object */ 
some object = rslvsp( _Usrq, "MYUSRQ", "MYLIB", AUTH ALL ); 
ensobj( some_object ); /* Force the object to disk. */ 


} 


Output 


** no screen output ** 
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Extract Exponent (EXTREXP) 


Format 
#include <QSYSINC/MIH/EXTREXP> 


int extrexp (double source); 


Description 
The extrexp function extracts the exponent portion of a floating-point scalar and 
returns the value as a 4 byte integer. 


Parameters 


source (input) 
An 8-byte floating-point number. 


Return Values 


value of source result 
0.0 0.0 
+/-INFINITY 32767 
NaN -32768 
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Example 

This example illustrates the use of the extrexp function. 

/ eesectet ee ese s ee eee ees See soe see see eee ee ee pees see sesecee 
/* Example Group: Computation and Branching <QSYSINC/MIH/EXTREXP> 
/* 

/* Function: extrexp (Extract Exponent) 

/* 

/* Description: This example uses 'extrexp' to return the 

/* exponent portion of the floating-point value. 

/* e.g. significand * 2 ** exponent 

/* extrexp(6734.219) = 1.6440964 « 2 ** 12 

/xeesest esl see Stet eee eect eee eee see eho eee cheese eee cues ete tees 
#include <QSYSINC/MIH/EXTREXP> 


#i 


in 


} 


nclude <stdio.h> 
t main(void) { 


double source = 6734.219; 
int exponent; 


exponent = extrexp(source) ; 
printf("The exponent = %d\n", exponent) ; 


Output 


Th 


e exponent = 12 
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Find Independent Index Entry (FNDINXEN) 


Format 
#include <QSYSINC/MIH/FNDINXEN> 


_SPCPTR fndinxen (_SPCPTR receiver, 
_SYSPTR index_obj, 
_IIX_Opt_List_T *option_list, 
_SPCPTR search_arg); 


Description 

The fndinxen function searches the independent index according to the search cri- 
teria specified in the option list and the search argument. The desired entry or 
entries are returned in the receiver. A pointer to the receiver area is also returned 
by the function. 


Parameters 
receiver (input/output) 
Pointer to the buffer to receive the returned entry or entries. 


index_obj (input) 
Pointer to the independent index object to be searched. 


option_list (input/output) 
Pointer to the option list template. This template contains additional information 
on the search. 


search_arg (input) 
Pointer to the search argument(s). 


Notes on Usage 
e The builtin function FNDINXEN also provides access to the MI instruction. 
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Example 

This example illustrates the use of the fndinxen function. 

fees sees ee soe eet eee eco see see te eee eee eee eee see eee */ 
/* */ 
/* Example Group: User Indexes <QSYSINC/MIH/FNDINXEN> */ 
/* */ 
/* Function: fndinxen (Find Index Entry) */ 
/* */ 
/* Description: Search for an entry using a particular customer */ 
/* number (stored as an integer). If an entry is */ 
[* found in the user index, then display the text */ 
/* of the entry to the screen. x/ 
/* */ 
/eeeeeeesse tees epee eel ee ee ee ee ee eee ee ee eee eet */ 


#include <QSYSINC/MIH/FNDINXEN> 
#include <QSYSINC/MIH/RSLVSP> 
#include <stdio.h> 


typedef struct Customer Entry { /* The format/layout of each */ 
int customer_number; /* entry in the user index. x*/ 
char last_name[ 50 ]; 
char first_name[ 40 ]; 
char phone_number[9]; /* Using phone format: 999-9999 «/ 
} Customer_Entry; 


/* Template used for setting */ 
_IIX_Opt_List_T | find_options; /* options for the "find". x/ 
/* Also used as the receiver */ 
/* for any returned information.*/ 


_SYSPTR index_ptr; /* Pointer to the user index. */ 


/* The receiver buffer for any */ 
Customer_Entry found_customer; /* entry that may be returned = */ 
/* from the 'fndinxen'. */ 


/* Our criterion is to find an +*/ 
int which_customer /* entry in the user index with */ 
= 55555; /* this customer number. */ 


int main(void) { 
/* Get a pointer to the *USRIDX «/ 
index_ptr = rslvsp( _Usridx, "MYUSRIDX", "MYLIB", AUTH ALL ); 


find_options.Rule = _FIND EQUALS; /* Find a matching customer x*/ 
/* number. */ 

find_options.Arg_Length /* The "search key" is the */ 
= sizeof(int); /* 4-byte integer customer */ 

/* number. */ 
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/* In case more than one entry 
find_options.Occ_Count = 1; /* exists with this customer 

/* number, only return the 

/* first entry found. 


/* Search for the entry that matches the customer number stored in 
/* ‘which_customer' and store the entry in 'found_customer'. The 

/* find options specified in the 'find_options' template are used to 
/* control the search. After the call to 'fndinxen', this template 
/* also stores the number of entries found. If one entry is found, 
/* its contents will be displayed to the screen. 


fndinxen( &found customer, index_ptr, &find options, &which customer ) 
if ( find_options.Ret Count == 0) 


printf("Customer number %d was not found.\n", which customer) ; 


else 
if (find_options.Ret_Count == 1) { 


printf("An entry was found for customer number: %d \n", 
which customer ); 


printf("Customer Name is: %s %s \n", found customer.first_name, 
found_customer.last_name) ; 


printf("Phone Number is:  %s \n",found customer.phone_number) ; 
} 
Output 
An entry was found for customer number: 55555 


Customer Name is: Mary Wilson 
Phone Number is: 777-7777 
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> 


fndrinvn 


Find Relative Invocation Number (FNDRINVN) 


Format 
#include <QSYSINC/MIH/FNDRINVN> 


int fndrinvn (_INV_Template_T *inv_t 
int srch_option, 
_SPCPTRCN srch_arg, 
char compare); 


Description 

The fndrinvn function searches a specified range of invocations until an invocation 
is found which satisfies the search criteria. If no invocation in the specified range 
satisfies the search criteria, a value of zero is returned by the function. Otherwise, 
the identity of the first invocation to satisfy the search criteria is returned by the 
function. The return value is specified relative to the starting invocation. A positive 
number indicates a displacement in the direction of newer invocations, while a neg- 
ative indicates a displacement in the direction of older invocations. 


Parameters 

inv_t (input) 
Pointer to the search range template or NULL. The search range template 
identifies the starting invocation and the range of the search. Specifying NULL 
will default to a range starting with the current invocation and proceeding 
through all existing older invocations. 


srch_option (input) 
Specifies the invocation attribute to be examined. 


srch_arg (input) 
Pointer to the search argument. This is a value between one and 16 bytes 
depending on the search option specified. 


compare (input) 
Specifies the compare operation. 
0X00 = Match. The function will identify the first invocation which matches the 
specified search criteria. 
0X01 = Mismatch. The function will identify the first invocation which does not 
match the specified search criteria. 


Notes on Usage 
e The starting invocation is skipped in the search and no exception is signalled if 
the search criterion is not satisfied. 


e The builtin functions FNDRINVN1 and _FNDRINVN2 also provide access to 
the MI instruction. 
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Example 
This example illustrates the use of the fndrinvn function. 
/eoesoe sos eset esse ob al see eee cee see see eee eae eee cee te 
/* 
/* Example Group: Machine Observation <QSYSINC/MIH/FNDRINVN> 
/* 
/* Function: fndrinvn (Find Relative Invocation Number) 
/* 
/* Description: This example uses 'fndrinvn' to search the call 
/* stack for an invocation with the specified 
/* invocation mark. Please Note: the 'fndrinvn' 
/* function itself has an entry on the call stack 
/* and this must be taken into account when 
/* calculating relative invocation offsets. This 
/* jis not necessary if either one of _FNDRINVN1 or 
/* _FNDRINVN2 builtins are used. 
/* 
/#ossese Hse et eee eee see eee see ee eee ee see eee oe eck 
#include <QSYSINC/MIH/FNDRINVN> 
#include <QSYSINC/MIH/MATINVAT> 
#include <string.h> 
#include <stdio.h> 
void func(void); 
int inv_mark, rel_off; 
_INV_Template_T  inv_t; 
int main(void) { 
func(); 
} 
void func(void) { 
memset (&inv_t, 0, sizeof(_INV_Template T)); 
inv_t.Inv_Offset = -2; /* main()'s invocation */ 
/* Get invocation mark for main() */ 
matinvat(&inv_mark, &inv_t, _MTVA_INV_MARK, sizeof(inv_mark)); 
/* Use the invocation mark from matinvat as the search criteria */ 
/* for fndrinvn. The relative invocation number returned should */ 
/* -2 indicating success at the invocation of main(). */ 
rel_off = fndrinvn(NULL, _FNDR_INV_MARK, &inv_mark, _FNDR_MATCH); 
printf("The search is stopped at %d invocations from the current\n", 
rel_off); 
} 
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Output 


The search is stopped at -2 invocations from the current 
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Increment Date (INCD) 


Format 
#include <QSYSINC/MIH/MIDTTM> 


void incd (_SPCPTR result_date, 
_SPCPTRCN source_date, 
_SPCPTRCN duration, 
_INST_Template_T3 *inst_t); 


Description 

The incd function increments the date by the date duration. The date specified by 
source_date is increased by the date duration specified by duration. The resulting 
date from the operation is placed in result_date. 


Parameters 
result_date (input/output) 
Pointer to the location to receive the result. 


source_date (input) 
Pointer to the source date. 


duration (input) 
Pointer to the packed decimal duration. 


inst_t (input) 
Pointer to the instruction template which defines the data definitional attributes 
for result_date, source_date, and duration. 


Notes on Usage 
e The builtin function _INCD also provides access to the MI instruction. 
e A macro version is available. 


e The DDATs for result_date and source_date must be identical. 
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Example 

This example illustrates the use of the incd function. 

/ depose eh sss es epee cose see see te eee See eee eee ee eee */ 
/* */ 
/* Example Group: Date/Time/Timestamp <QSYSINC/MIH/MIDTTM> */ 
/* */ 
/* Function: incd (Increment Date) */ 
/* */ 
/* Description: This example uses 'incd' to increment the date */ 
/* by the date duration. */ 
/* */ 
[Resse esl see Stet eee ee Seo se see el se ee eee eee sees ee eet eee eee */ 
#include <QSYSINC/MIH/MIDTTM> 

#include <string.h> 

#include <stdio.h> 

#include <stdlib.h> 

#include <stddef.h> 

#include <decimal.h> 


/* Internal format for start of Gregorian timeline: January 1, 0001 */ 
#define GREGORIAN TIMELINE START 1721424 


/* Internal format for end of Gregorian timeline: January 1, 10000 +*/ 
#define GREGORIAN TIMELINE END 5373485 


int main(void) { 


_INST_Template_T3  *inst_t3; 


_DDAT_T 


*ddat_tl, *ddat_t2; 


_Era_Table_T xera_tl; 
_Calendar_Table T *cal_tl; 


int DDAT_Length, Calendar Offset; 
int DDAT_Size, Template Size; 

int DDAT_Offset1, DDAT_Offset2; 
char result_d[11]; 

char source _d[1l] = "1993-01-30"; 
decimal (8,0) duration = 01610801D; 


DDAT_Length = sizeof(_DDAT_T) + 


2*(sizeof(_Calendar_ Table T)) - sizeof(short) + 
sizeof(_Era_ Table T) - 1; 


Calendar Offset = offsetof(_DDAT T, Tables) + 


sizeof(_Era_ Table T); 


DDAT_Size = 2*DDAT_Length + 
2*(sizeof(int)) + /* DDAT Offset */ 
10 + /* reserved4 = */ 
sizeof(short) + /* Num_DDATs */ 
sizeof (int); /* DDAT Size */ 


Template Size = 2*DDAT_Length + offsetof(_INST_Template_T3, DDAT) + 


sizeof(int); /* ddat offset */ 
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DDAT Offsetl = (offsetof(_INST Template T3, DDAT) - 
offsetof(_INST Template _T3, DDAT Size)) + 
sizeof(int); /* DDAT2 offset */ 

DDAT_ Offset2 = (offsetof(_INST Template T3, DDAT) - 
offsetof(_INST Template _T3, DDAT Size)) + 
DDAT_ Length + sizeof(int); /* DDAT2 offset */ 

inst_t3 = (_INST_ Template T3 *)malloc(Template Size); 


/* Fill in Instruction Template */ 


memset(inst_t3, '\O', sizeof(_INST_ Template T3)); 


inst_t3->Template Size = Template Size; 
inst_t3->DDAT_1 = 1; 
inst_t3->DDAT_2 = 1; 
inst_t3->DDAT_3 inl 
inst_t3->Length_1 = 10; 
inst_t3->Length_2 = 10; 
inst_t3->F_Digits = 0; 
inst_t3->T_Digits = 8; 
inst_t3->Indicators = _OQUT_ADJUST | _IN ADJUST; 
inst_t3->DDAT_Size = DDAT_Size; 
inst_t3->Num_DDATs anes 
inst_t3->DDAT_ Offset [0] = DDAT Offsetl; 


*(inst_t3->DDAT_Offset + 1)= DDAT_Offset2; 
/* Set table pointers within instruction template */ 


ddat_tl = (_DDAT_T *)&(inst_t3->DDAT Offset + 2); 


era_tl = (_Era_Table T *)&(ddat_t1->Tables); 

cal_ tl = (Calendar Table T *)((char *)ddat_t1 + Calendar Offset); 
ddat_t2 = (_DDAT T *)((char *)ddat_t1 + DDAT Length); 

/* Fill in DDAT1 */ 
ddat_t1->DDAT_Length = DDAT_Length; 

ddat_t1->Format_Code = _I1SO_DATE; 


ddat_t1->Calendar_Offset = Calendar Offset; 


/* Fill in Era Table for DDAT1 x/ 


era_tl->Num_Elems = 1; 

era_tl->Element[0].Origin_Date = GREGORIAN TIMELINE START; 
era_t1->Element[0].Era_Name[0] = 'A'; 
era_t1->Element[0].Era_Name[1] = 'D'; 


/* Fill in Calendar Table for DDAT1 */ 
cal_t1->Num_Elems = 2; 
cal_tl->Element->Effect_Date = GREGORIAN TIMELINE START; 
cal_tl->Element->Type = 0x0001; 


memset (cal_tl->Element->reserved, '\0', 10); 
(cal_t1->Element+1)->Effect_Date = GREGORIAN TIMELINE_END; 
(cal_t1->Element+1) ->Type = 0; 

memset ((cal_t1->Element+1)->reserved, '\O', 10); 
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/* Fill in DDAT 2 */ 
ddat_t2->DDAT_Length = DDAT_Length; 
ddat_t2->Format_Code = _DATE_DUR; 


ddat_t2->Calendar_Offset = Calendar Offset; 
incd(result_d, source_d, &duration, inst_t3); 
result_d[10] = '\0'; 


printf("The resulting date is %s\n", result_d); 


} 


Output 
The resulting date is 2154-10-01 


Machine Interface Library Functions 119 


inct 


Increment Time (INCT) 


Format 
#include <QSYSINC/MIH/MIDTTM> 


void inct (_SPCPTR result_time, 
_SPCPTRCN source_time, 
_SPCPTRCN duration, 
_INST_Template_T3 *inst_t); 


Description 

The inct function increments the time by the time duration. The time specified by 
source_time is increased by the time duration specified by duration. The resulting 
time from the operation is placed in result_time. 


Parameters 
result_time (input/output) 
Pointer to the location to receive the result. 


source_time (input) 
Pointer to the source time. 


duration (input) 
Pointer to the packed decimal duration. 


inst_t (input) 
Pointer to the instruction template which defines the data definitional attributes 
for result_date, source_date and duration. 


Notes on Usage 
e The DDATs for result_time and source_time must be identical. 
¢ The builtin function _INCT also provides access to the MI instruction. 


e Amacro version is available. 


120 = Mi Library Reference 


Example 
This example illustrates the use of the inct function. 


/* Examp] 
/* Functi 


/* Descri 


#include 
#include 
#include 
#include 
#include 
#include 


int main( 


_INST_T 
_DDAT_T 


int 
int 
int 
char 


char 
decimal 


e Group: 
on: 


ption: 


<QSYSINC/MI 
<string.h> 
<stdio.h> 

<stdlib.h> 
<stddef.h> 
<decimal .h> 


void) { 


emplate_T3 


(6,0) 


Date/Time/Timestamp <QSYSINC/MIH/MIDTTM> 


inct (Increment Time) 


This example uses 'inct' to increment the time 


by the time duration. 


H/MIDTTM> 


*inst_t3; 
*ddat_tl, *ddat_t2; 


DDAT_Length, Calendar Offset; 
DDAT_Size, Template Size; 
DDAT_Offset1, DDAT_Offset2; 


result_d[9]; 
source d[9] = "11.05.30"; 
duration = 000205D; 


DDAT_Length = sizeof(_DDAT_T) + 


Calenda 


DDAT_Si 


Temp] at 


2*(s 
size 


r_Offset = 


ze = 


e Size = 


DDAT_Offset1 7 


DDAT_Offset2 = 


izeof(_Calendar_Table T)) - sizeof(short) + 
of(_Era_ Table T) - 1; 


offsetof(_DDAT T, Tables) + 
sizeof(_Era_ Table T); 


2*DDAT_Length + 
2*(sizeof(int)) + /* DDAT Offset */ 


10 + /* reserved4  */ 
sizeof(short) + /* Num_DDATs = */ 
sizeof (int); /* DDAT Size */ 


inct 


2*DDAT_Length + offsetof(_INST_Template_T3, DDAT) + 


sizeof(int); /* ddat offset */ 


(offsetof(_INST Template 13, DDAT) - 
offsetof(_INST Template _T3, DDAT Size)) + 
sizeof(int); /* DDAT2 offset */ 


(offsetof(_INST Template 13, DDAT) - 
offsetof(_INST Template _T3, DDAT Size)) + 
DDAT_ Length + sizeof(int); /* DDAT2 offset */ 


Machine Interface Library Functions 


121 


inct 


inst_t3 = (_INST_ Template T3 *)malloc(Template Size); 
/* Fill in Instruction Template */ 
memset(inst_t3, '\O', sizeof(_INST_ Template T3)); 


inst_t3->Template Size = Template Size; 
inst_t3->DDAT_1 = 1 
inst_t3->DDAT_2 = 1 
inst_t3->DDAT_3 = 2; 
inst_t3->Length_1 = 83 
8 
0 
6 


> 
> 


> 


inst_t3->Length_2 5 
inst_t3->F_Digits = 
inst_t3->T_Digits 7 


> 


> 


inst_t3->Indicators = _NO_ADJUST_OR_TOLERATE; 
inst_t3->DDAT_Size = DDAT_Size; 
inst_t3->Num_DDATs = 2; 

inst_t3->DDAT_ Offset [0] = DDAT Offset1; 


*(inst_t3->DDAT_Offset + 1)= DDAT_Offset2; 


ddat_tl = (_DDAT T *)&(inst_t3->DDAT Offset + 2); 


ddat_t2 = (_DDATT *)((char *)ddat_t1 + DDAT Length); 
/* Fill in DDAT1 x/ 
ddat_t1->DDAT_Length = DDAT_Length; 
ddat_t1->Format_Code = _ISO_TIME; 
ddat_t1->Hour_Zone = 24; 

ddat_t1->Min_Zone = 60; 


ddat_t1->Calendar_Offset = Calendar Offset; 


/* Fill in DDAT2 */ 
ddat_t2->DDAT_Length = DDAT_Length; 
ddat_t2->Format_Code = _TIME_DUR; 


ddat_t2->Hour_Zone 7 
ddat_t2->Min_Zone 
ddat_t2->Calendar_Offset 


0; 
Q; 
Calendar_Offset; 
inct(result_d, source_d, &duration, inst_t3); 
result_d[8] = '\0'; 


printf("The resulting time is %s\n", result_d); 


} 


Output 
The resulting time is 11.07.35 
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Increment Timestamp (INCTS) 


Format 
#include <QSYSINC/MIH/MIDTTM> 


void incts (_SPCPTR result_timestamp, 
_SPCPTRCN source_timestamp, 
_SPCPTRCN duration, 
_INST_Template_T3 *inst_t); 


Description 

The incts function increments the date by the timestamp. The timestamp specified 
by source_timestamp is increased by the date, time, or timestamp duration speci- 
fied by duration. The resulting timestamp from the operation is placed in 
result_timestamp. 


Parameters 
result_timestamp (input/output) 
Pointer to the location to receive the result. 


source_timestamp (input) 
Pointer to the source timestamp. 


duration (input) 
Pointer to the packed decimal duration. 


inst_t (input) 
Pointer to the instruction template which defines the data definitional attributes 
for result_timestamp, source_timestamp, and duration. 


Notes on Usage 
e The DDATs for result_timestamp and source_timestamp must be identical. 


e The builtin function _INCTS also provides access to the MI instruction. 


e Amacro version is available. 
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Example 


This example illustrates the use of the incts function. 


/* Example Group: 
/* Function: 


/* Description: 


Date/Time/Timestamp <QSYSINC/MIH/MIDTTM> 
incts (Increment Timestamp) 


This example uses 'incts' to increment the time- 
stamp by the timestamp duration. 


#include <QSYSINC/MIH/MIDTTM> 


#include <stdio.h> 
#include <stdlib.h> 
#include <stddef.h> 
#include <string.h> 


#include <decimal.h> 


/* Internal format for start of Gregorian timeline: January 1, 0001 */ 
#define GREGORIAN TIMELINE START 1721424 


/* Internal format for end of Gregorian timeline: January 1, 10000 */ 
#define GREGORIAN TIMELINE END 5373485 


int main(void) { 


_INST_Template_T3  *inst_t3; 
_DDAT_T *ddat_tl, *ddat_t2; 
_Era_Table T xera_tl; 
_Calendar_Table T *cal_tl; 


int DDAT_Length, Calendar Offset; 

int DDAT_ Size, Template Size; 

int DDAT_Offset1, DDAT_Offset2; 

char result_d[27]; 

char source_d[27] = "1993-01-17-11.05.30.000000"; 
decimal (20,6) duration = 00000203012005.000000D; 


DDAT_Length = sizeof(_DDAT_T) + 
2*(sizeof(_Calendar_Table T)) - sizeof(short) + 
sizeof(_Era_ Table T) - 1; 


Calendar Offset = offsetof(_DDAT T, Tables) + 
sizeof (_Era_Table 1); 


DDAT_Size = 2*DDAT_Length + 
2*(sizeof(int)) + /* DDAT Offset */ 
10 + /* reserved4 = */ 
sizeof(short) + /* Num_DDATs~ */ 
sizeof (int); /* DDAT Size */ 
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Template Size = 2*DDAT_Length + offsetof(_INST_Template_T3, DDAT) + 
sizeof(int); /* ddat offset */ 


DDAT Offsetl = (offsetof(_INST Template 13, DDAT) - 
offsetof(_INST Template _T3, DDAT Size)) + 
sizeof(int); /* DDAT2 offset «/ 

DDAT Offset2 = (offsetof(_INST Template 13, DDAT) - 
offsetof(_INST Template _T3, DDAT Size)) + 
DDAT_ Length + sizeof(int); /* DDAT2 offset */ 

inst_t3 = (_INST_ Template T3 *)malloc(Template Size); 


/* Fill in Instruction Template */ 


memset(inst_t3, '\O', sizeof(_INST_ Template T3)); 


inst_t3->Template Size = Template Size; 
inst_t3->DDAT_1 = 1; 
inst_t3->DDAT_2 = 1; 
inst_t3->DDAT_3 S25 
inst_t3->Length_1 = 26; 
inst_t3->Length_2 = 26; 
inst_t3->F_Digits = 6; 
inst_t3->T_Digits = 20; 
inst_t3->Indicators = _QUT_ADJUST | _IN ADJUST; 
inst_t3->DDAT_Size = DDAT_Size; 
inst_t3->Num_DDATs S25 
inst_t3->DDAT_ Offset [0] = DDAT Offset1; 


*(inst_t3->DDAT_Offset + 1)= DDAT_Offset2; 
/* Set table pointers within instruction template */ 


ddat_tl = (_DDAT_T *)&(inst_t3->DDAT Offset + 2); 


era_tl = (_Era_Table T *)&(ddat_t1->Tables); 

cal_ tl = (Calendar Table T *)((char *)ddat_t1 + Calendar Offset); 
ddat_t2 = (_DDATT *)((char *)ddat_t1 + DDAT Length); 

/* Fill in DDAT1 */ 


ddat_t1->DDAT_Length 
ddat_t1->Format_Code 


DDAT_Length; 
_SAA_TIMESTAMP ; 


ddat_t1->Hour_Zone = 24; 

ddat_t1->Min_Zone = 60; 

ddat_t1->Calendar_Offset = Calendar Offset; 

/* Fill in Era Table for DDAT1 */ 
era_tl->Num_Elems = 1; 


era_tl->Element[0].Origin_Date = GREGORIAN TIMELINE START; 
era_t1->Element[0].Era_Name[0] 'A's 
era_t1->Element[0].Era_Name[1] = 'D'; 


/* Fill in Calendar Table for DDAT1 */ 


cal_t1->Num_Elems = 2; 
cal_tl->Element->Effect_Date = GREGORIAN TIMELINE START; 
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cal_tl->Element->Type = 0x0001; 

memset (cal_t1->Element->reserved, '\0', 10); 
(cal_t1->Element+1)->Effect_Date = GREGORIAN TIMELINE_END; 
(cal_t1->Element+1)->Type = 0; 

memset ((cal_t1->Element+1)->reserved, '\O', 10); 


/* Fill in DDAT 2 */ 
ddat_t2->DDAT_Length = DDAT_Length; 
ddat_t2->Format_Code = _TIMESTAMP_DUR; 
ddat_t2->Hour_Zone = 0Q; 

ddat_t2->Min_Zone = 0; 


ddat_t2->Calendar_Offset = Calendar Offset; 
incts(result_d, source _d, &duration, inst_t3); 


result_d[26] = '\0'; 
printf("The resulting timestamp is %s\n", result_d); 


} 


Output 
The resulting timestamp is 1996-12-20-12.25.35.000000 


126 = Mi Library Reference 


insinxen 


Insert Independent Index Entry (INSINXEN) 


Format 
#include <QSYSINC/MIH/INSINXEN> 


void insinxen (_SYSPTR new_entry, 
_SPCPTR index_obj, 
_IIX_Opt_List_T *option_list); 


Description 

The insinxen function inserts one or more new entries into an independent index, 
according to the criteria specified. Each entry is inserted into the index based on 
the binary value of the argument. 


Parameters 
index_obj (input) 
Pointer to the independent index object to receive the new entry or entries. 


new_entry (input) 
Pointer to the new entry or entries to be inserted. 


option_list (input) 
Pointer to the option list template. This template contains additional information 
regarding the insertion of the new entry or entries. 


Notes on Usage 
e The builtin function _INSINXEN also provides access to the MI instruction. 


e When a NULL is passed as the second operand of insinxen, error message 
MCH5601 or MCH3601 will be generated. 
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Example 
This example illustrates the use of the insinxen function. 
feoesoe sos oust ese oes e tse eee eee ce sche eee ete ee cee eee eo ee ee */ 
/* */ 
/* Example Group: User Indexes <QSYSINC/MIH/INSINXEN> */ 
/* */ 
/* Function: insinxen (Insert Index Entry) */ 
/* */ 
/* Description: This example will insert 3 entries into the user */ 
/* index. Each entry will consist of a customer */ 
/* number, first name, last name, and phone number. */ 
/* The customer number (stored as an integer) will */ 
/* be used as the key. ‘insinxen' will insert each */ 
/* entry at the appropriate position based on the */ 
/* value stored in the key field of the entry */ 
/* (entries are sorted in ascending order). */ 
/* */ 
/* This example operates on a keyed user index that +*/ 
/* has fixed-length entries (note that entries in */ 
/* a user index have a maximum size of 120 bytes). */ 
/* */ 
[eaters n see nee onto ee ee ee ee toe eee to see ee ees */ 
#include <QSYSINC/MIH/INSINXEN> 
#include <QSYSINC/MIH/RSLVSP> 
#include <stdio.h> 
typedef struct Customer Entry { /* The format/layout of each */ 
int customer_number; /* entry in the user index. x*/ 
char last_name[ 50 ]; 
char first_name[ 40 ]; 
char phone_number[9]; /* Using phone format: 999-9999 «/ 
} Customer_Entry; 
/* Template used for setting */ 
_IIX_Opt_List_T insert_options; /* options for the "insert". x/ 
/* Also used as the receiver */ 
/* for any returned data. */ 
_SYSPTR index_ptr; /* Pointer to the user index. ¥*/ 
/* Declare and initialize a */ 
/* few example entries. x/ 
Customer Entry customerl = {9999999, "Smith", "John", "555-5555" }, 
customer2 = { 55555, "Wilson", "Mary", "777-7777" }, 
customer3 = { 1, "Chan", "Julie", "123-4567" }; 
int main(void) { 
/* Get a pointer to the *USRIDX «/ 
index_ptr = rslvsp( Usridx, "MYUSRIDX", "MYLIB", AUTH ALL ); 
/* For Keyed User Indexes must */ 
insert_options.Rule /* specify “insert and replace" */ 
= _INSERT_REPLACE; /* instead of just "insert". x*/ 
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/* 1 entry is to be inserted forx/ 
insert_options.Occ Count = 1; /* each use of ‘insinxen'. You */ 
/* could also have all 3 entriesx/ 
/* inserted with one 'insinxen'.«/ 


/eereee ose ee eee nee eee eee eee eee eee ee ete ee ee ee */ 
/* Insert each of the three entries into the user index and check */ 
/* the return count to ensure that each insert was successful. */ 
[Roce osteo se sees este ee eet ees eons sees Lee tee sce ee ee eee ees */ 


insinxen( index_ptr, &customerl, &insert_options ); 


if (insert_options.Ret_Count != 1) /* If 1 entry was not inserted, */ 
/* then it either failed or more*/ 

printf("First Insert Failed\n"); /* than 1 entry was inserted */ 

/* (but we only asked for 1 to */ 

/* be inserted). */ 


insinxen( index_ptr, &customer2, &insert_options ); 
if (insert_options.Ret Count != 1) 

printf("Second Insert Failed\n"); 
insinxen( index_ptr, &customer3, &insert_options ); 
if (insert_options.Ret_Count != 1) 


printf("Third Insert Failed\n"); 
} 


Output 


** No output ** 
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Lock Object (LOCK) 


Format 
#include <QSYSINC/MIH/LOCK> 


void lock (_SYSPTR object, 
MI_Time wait_time, 
char lock state); 


Description 
The lock function requests that a single lock for the system object be allocated to 
the issuing process. 


Parameters 
object (input) 
Pointer to the system object to be locked. 


wait_time (input) 
The wait time requested. This specifies the maximum amount of time that a 
process competes for the requested lock. Use the mitime function to form this 
value. 


lock_state (input) 
The lock state requested. 


Notes on Usage 
e The lock request type will be set for the user by default, depending on what is 
specified as the wait time. The following rule will be used: If wait_time = 0, 
_LOCK_NORMAL will be used as the request type. If wait_time > 0, 
_LOCK_SYNCH will be used as the request type. 


¢ The lock entry will always be marked as active by the lock function. So, for the 
function version it is not necessary to OR the lock state with 
_LOCK_ENTRY_ACTIVE. 


¢ The builtin function LOCK and macro Lock also provide access to the MI 
instruction. 
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Example 


This example illustrates the use of the lock function. 


/* Example Group: 
/* Function: 


/* Description: 


#include <QSYSINC/MI 
#include <QSYSINC/MI 
#include <miptrnam.h 
#include <stdio.h> 

#include <stdlib.h> 


_SYSPTR some_ob 

_MI_Time timeout 

int hours 
minutes 
seconds 
hundred 


int main(void) { 


some object = rsl 


Locks <QSYSINC/MIH/LOCK> 
lock (Lock Object) 


This example illustrates the use of the 'lock' 
function by placing an Exclusive-No-Read (LENR) 
lock on an object (a user queue in this example). 
This kind of lock prevents any other user (job) 
from placing any kind of lock on the same object 
(using the 'lock' function or ALCOBJ command). 
Several types of locks can be placed on objects. 


This example shows how a timeout value is created 
using the 'mitime' and passing the timeout value 
to the 'lock' function. If the lock request 
cannot be satisfied within the timeout value, an 
exception will be generated/raised. 


The DSPJOB command is called using the 'system' 
function to display all of the object locks for 
the job in which this program is run. 


H/LOCK> 
H/RSLVSP> 


> 


ject; /* The object being locked. 
3 /* Amount of time to wait for 
/* the lock to be placed. 
= Q, /* Time components used to 
Q, /* create an MI_Time value 
= 12, /* that can be passed to the 
ths = 0; /* 'lock' function. 


/* Get a pointer to the object 
vsp( _Usrq, "MYUSRQ", "MYLIB", AUTH ALL ); 


/* Format an 'mitime' value to represent the timeout to be used by 


/* the 'lock' funct 
/* (LENR) lock on t 
/* in the specified 


ion when trying to obtain an Exclusive-No-Read 
he object. If the lock request cannot be satisfied 
amount of time, then an exception will be raised. 


/* The CL DSPJOB command is called to display all of the object locks 
/* owned by the job/process that runs this program. 
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*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 


*/ 
*/ 
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mitime( &timeout, hours, minutes, seconds, hundredths ); 
lock( some_object, timeout, _LENR LOCK ); 
system( "DSPJOB OPTION(*JOBLCK)" ); 


} 


Output 
Display Job Locks 
System: TORAS4YL 
Job: OMXNA3S4 User: VISCA Number: 009616 
Job status: ACTIVE 


Type options, press Enter. 
5=Display job member locks 


Object Member 
Opt Object Library Type Lock Status Locks 
MAIN QSYS *MENU * SHRNUP HELD 
*SHRNUP HELD 
MYUSRQ MYLIB *USRQ *EXCL HELD 
OMXNA3S4 QSYS *DEVD *EXCLRD HELD 


*EXCLRD HELD 

*EXCLRD HELD 

*EXCLRD HELD 

QADM QSYS *LIB *SHRRD HELD 
More... 

F3=Exit F5=Refresh F10=Display job record locks F12=Cancel 
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Lock Space Location (LOCKSL) 


Format 
#include <QSYSINC/MIH/LOCKSL> 


void locks] (_SPCPTR location, 
char lock_state); 


Description 

The locksl function grants the space location to the issuing process according to 
the lock request. For this function, if the requested lock cannot be immediately 
granted, the process will enter a synchronous wait for the lock for a period up to 
the interval specified by the process default time-out value. 


Parameters 
location (input) 
Pointer to the space location to be locked. 


lock_state (input) 
The lock type request. 


Notes on Usage 
e The builtin functions LOCKSL1 and _LOCKSL2 also provide access to the MI 
instruction. 


e¢ The _LOCKSL2 builtin supports multiple space location lock requests. 
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Example 

This example illustrates the use of the locksl function. 

/eoesoe sos oe tesa see e tse eee eee eee eee eee eee eee ee 
/* 

/* Example Group: Locks <QSYSINC/MIH/LOCKSL> 

/* 

/* Function: locks] (Lock Space Location) 

/* 

/* Description: Place an Exclusive-No-Read (LENR) on a particular 
/* byte (space location) of some object (a user 

/* queue in this example). This type of lock is 

/* "symbolic" in that it does not prevent the space 

/* location from being referenced or updated. 

/* 

[xeoseon poste oe ee eb e ee te ee eee ee eee ee ee ee ee eee eee 


#include <QSYSINC/MIH/LOCKSL> 
#include <QSYSINC/MIH/RSLVSP> 
#include <QSYSINC/MIH/SETSPPFP> 
#include <QSYSINC/MIH/MATOBJLK> 
#include <stdio.h> 


/* The object from which some 
_SYSPTR some_object; /* byte (space) location will 
/* be locked. 


_SPCPTR some_byte; /* The pointer to the location 
/* that is being locked. 


/* The receiver template used 
_MOBJL_Template_T allocated_locks; /* by 'matobjlk'. 
int main(void) { 


/* Get a pointer to the object 
some object = rslvsp( _Usrq, "MYUSRQ", "MYLIB", _AUTH_ALL ); 


/* Set a space pointer from 
/* the system pointer. 
some_byte = setsppfp( some object ); 


/* Request the Exclusive-No-Read (LENR) lock on the space location. 

/* A default timeout called the "Process Default Timeout" is used as 
/* the timeout value. If the lock request is not satisfied in that 

/* time, an exception is raised. 


locks1( some_byte, _LENR LOCK ); 
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/eoeoue Sot eee eee ee eee oe eee cee eee cso eee ee */ 
/* In order to verify that the LENR lock was placed on the space x*/ 
/* location (byte), we can look at the bit pattern returned by */ 


/* ‘'matobjlk' in the 'Lock_Alloc' field of the template. The fifth */ 
/* bit (bit 4) of this field represents the Lock-Exclusive-No-Read */ 
/* (LENR) lock. By using the bitwise AND (&) operator, we can */ 
/* determine if the bit is set by ANDing it with the provided bit */ 
/* mask, _LENR_LOCK (which is defined in <milock.h> as hex 08 - bit = +*/ 
/* pattern 0000 1000). */ 


allocated_locks.Template Size = sizeof( MOBJL_ Template T ); 


matobjlk( &allocated_locks, some byte ); 


if ( allocated_locks.Lock_Alloc & _LENR_LOCK ) { 


printf("There is an Exclusive-No-Read lock on the space \n"); 
printf("location with address: %p \n\n", some_byte ); 

} 

else 
printf("Error. The LENR lock request was not satisifed. \n"); 


} 
Output 


There is an Exclusive-No-Read lock on the space 
location with address: SPP:0401MYLIB :QaO02MYUSRQ :0:0:e28 
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Lock Space Location with Time-Out (LOCKSL2) 


Format 
#include <QSYSINC/MIH/LOCKSL2> 


void locks12 (_SPCPTR location, 
_MI_Time wait_time, 
char lock_state); 


Description 
The locksl2 function grants the space location to the issuing process according to 
the lock request. 


Parameters 
location (input) 
Pointer to the space location to be locked. 


wait_time (input) 
Wait_time value. Specifies the amount of time that the process competes for 
the requested lock. 


lock_state (input) 
The lock type request. 


Notes on Usage 
¢ The lock request type will be set for the user by default, depending on what is 
specified as the wait time. The following rule will be used: If wajit_time = 0, 
_LOCK_NORMAL will be used as the request type. If wait_time > 0, 
_LOCK_SYNCH will be used as the request type. 


e The builtin functions LLOCKSL1 and _LOCKSL2 also provide access to the MI 
instruction. 


e¢ The _LOCKSL2 builtin supports multiple space location lock requests. 
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Example 

This example illustrates the use of the locksl2 function. 

/ ees Sees ees eee eee bese oes ee see eee eee eee eee ese eee eee */ 
/* */ 
/* Example Group: Locks <QSYSINC/MIH/LOCKSL> */ 
/* */ 
/* Function: locks12 (Lock Space Location with a timeout) */ 
/* */ 
/* Description: Place an Exclusive-Allow-Read (LEAR) on a specific */ 
/* byte (space location) of some object (a user x/ 
/* queue in this example). ‘locks12' is similar to */ 
/* ‘locks1]' except that it allows you to specify a */ 
/* timeout value instead of using the default process */ 
/* timeout value. x/ 
/* */ 
/¥oseepe esos sees cee oc eee eee ee eee cee eee ee se eee eee */ 


#include <QSYSINC/MIH/LOCKSL> 
#include <QSYSINC/MIH/RSLVSP> 
#include <QSYSINC/MIH/SETSPPFP> 
#include <QSYSINC/MIH/MATOBJLK> 
#include <stdio.h> 


/* The receiver template used */ 


_MOBJL_Template_T allocated_locks; /* by 'matobjlk'. */ 
/* The object from which some */ 

_SYSPTR some_object; /* byte (space) location will */ 
/* locked. */ 

_SPCPTR some_byte; /* The pointer to the location */ 
/* that is being locked. x*/ 

_MI_Time timeout; /* Amount of time to wait for */ 
/* the lock to be placed. x*/ 

int hours = Q, /* Time components used to */ 
minutes = 0, /* create an MI Time value x*/ 

seconds = 10, /* that can be passed to the’ */ 

hundredths = 0; /* 'lock' function. */ 


int main(void) { 
/* Get a pointer to the object */ 
some object = rslvsp( _Usrq, "MYUSRQ", "MYLIB", _AUTH_ALL ); 


/* Set a space pointer from */ 
/* the system pointer. */ 
some byte = setsppfp( some object ); 
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/* Format an 'mitime' value to represent the timeout to be used by */ 
/* the 'lock' function when trying to obtain an Exclusive-Allow-Read */ 
/* (LEAR) lock on the object. If the lock request cannot be satisfied */ 
/* in the specified amount of time, then an exception will be raised. */ 
/* The CL DSPJOB command is called to display all of the object locks */ 
/* owned by the job/process that runs this program. */ 


mitime( &timeout, hours, minutes, seconds, hundredths ); 


locks12( some_byte, timeout, LEAR LOCK ); 


/eeSesebe ese Sots see let se eee ete sees se eee eee see sted */ 
/* In order to verify that the LEAR lock was placed on the space x/ 
/* location (byte), we can look at the bit pattern returned by */ 


/* ‘'matobjlk' in the 'Lock_Alloc' field of the template. The fourth +*/ 
/* bit (bit 3) of this field represents the Lock-Exclusive-Allow-Read */ 
/* (LEAR) lock. By using the bitwise AND (&) operator, we can */ 
/* determine if the bit is set by ANDing it with the provided bit */ 
/* mask, _LEAR_LOCK (which is defined in <milock.h> as hex 10 - bit = +*/ 
/* pattern 0001 0000). */ 


allocated_locks.Template Size = sizeof( MOBJL_ Template T ); 


matobjlk( &allocated_locks, some byte ); 


if ( allocated_locks.Lock_Alloc & _LEAR_LOCK ) { 


printf("There is an Exclusive-Allow-Read lock on the space \n"); 
printf("location with address: %p \n\n", some byte ); 

} 

else 
printf("Error. The LEAR lock request was not satisifed. \n"); 


} 
Output 


There is an Exclusive-Allow-Read lock on the space 
location with address: SPP:0401MYLIB :QaQ02MYUSRQ :0:0:eda 


138 = MI Library Reference 


matactat 


Materialize Activation Attribute (MATACTAT) 


Format 
#include <QSYSINC/MIH/MATACTAT> 


void matactat (_MTACT_Template_T *receiver 
unsigned int act_mark, 
char attr_selection); 


Description 
The matactat function materializes the information for the program activation into 
the receiver template. 


Parameters 
receiver (input/output) 
Pointer to the receiver template. 


act_mark (input) 
The activation mark of the activation whose attributes are to be materialized. A 
value of zero indicates a request for information about the activation of the 
invoking program. 


attr_selection (input) 
Identifies the information to be materialized. 


Notes on Usage 
e The builtin function MATACTAT also provides access to the MI instruction. 
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Example 

This example illustrates the use of the matactat function. 

/eoesoe sos oeet ese eee alse eee coe see shee eee eee eee eon te 
/* 

/* Example Group: Program Execution <QSYSINC/MIH/MATACTAT> 

/* 

/* Function: matactat (Materialize Activation Attributes) 

/* 

/* Description: This example uses 'matactat' to materialize 

/* the program model of the caller to main(). 

/* Please note: the invocations for the ILE program 
/* entry procedure and for the matinvat library 

/* function, must be taken into account when 

/* calculating the relative invocation offset. 

/* 

/xesserSteoss pessoas see eee ete ee eee eee eee eee eee eee 


#include <stdio.h> 
#include <string.h> 
#include <stdlib.h> 
#include <QSYSINC/MIH/MATACTAT> 
#include <QSYSINC/MIH/MATINVAT> 


#define MY_CALLER -3 /* -2 = C_PEP (program entry procedure) */ 


/* -1 = main() */ 
/* @ = matinvat library function */ 
int main(void) { 
unsigned act_mark; 
_INV_Template_T inv_t; 


_MTACT_Template_T mtact_t; 
memset (&inv_t, 0, sizeof(_INV_Template T)); 
inv_t.Inv_Offset = MY_CALLER; /* caller's invocation */ 


/* Materialize the activation mark of our caller */ 
matinvat(&act_mark, &inv_t, _MTVA_ACT MARK, sizeof(act_mark)); 


mtact_t.Template Size = sizeof(_MTACT_Template_T); 
matactat(&mtact_t, act_mark, _MTACT_BASIC_ACT_ATTR); 


/* Program Models: OPM = 0x00, ILE = 0x01 */ 
printf("The program model of our caller is %x\n", 
mtact_t.Data.Basic_Attr.Program_Mode1); 
} 


Output 


The program model of our caller is 1 
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Materialize Access Group Attributes (MATAGAT) 


Format 
#include <QSYSINC/MIH/MATAGAT> 


void matagat (_MAGAT Template_T «receiver, 
_SYSPTR access group); 


Description 
The matagat function materializes the attributes of the access group and the iden- 
tification of objects currently contained in the access group. 


Parameters 
receiver (input/output) 
Pointer to the receiver template. 


access_group (input) 
Pointer to the access group whose attributes are to be materialized. 


Notes on Usage 
e The builtin function MATAGAT also provides access to the MI instruction. 
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Example 

This example illustrates the use of the matagat function. 

feocsoe sos oeet ese tesa tse eee ee see see ee eee eee eee See */ 
/* */ 
/* Example Group: Resource Management Data(RMD) <QSYSINC/MIH/MATAGAT>*/ 
/* */ 
/* Function: matagat (Materialize Access Group Attributes) +*/ 
/* */ 
/* Description: This example uses 'matagat' to materialize all */ 
/* of the objects that are part of an Access Group. +*/ 
/* Since the Process Access Group (PAG) is a readily +*/ 
/* available Access Group (using 'matpratr'), it */ 
/* will be used as the Access Group of which the */ 
/* attributes will be materialized. */ 
/* */ 
/* Access Groups should not be confused with */ 
/* Activation Groups. */ 
/* */ 
/* Note: This example will only work on a system running */ 
/* with security level 30 or lower since it attempts */ 
/* to materialize the PAG. */ 
/* */ 
/eececenus seats Se ste eet eee cee eee see eee sce oe eee Sete eee */ 


#include <QSYSINC/MIH/MATAGAT> 
#include <QSYSINC/MIH/MATPRATR> 
#include <stdio.h> 
#include <stdlib.h> 


/* 
_MPRT_Template_T process attributes; /* 
/* 


/* 
/* 


Receiver template that will*/ 
contain a pointer to the +*/ 
Process Access Group (PAG) .*/ 


Pointer to the receiver */ 
template for 'matagat'. */ 


_MAGAT_Template_T *access_group_attributes; 


/* 
_SYSPTR access group ptr; /* 
/* 


/* 
_SYSPTR xobject_pointer; /* 
/* 


int object_count, /* 


/* 


/* 
object, /* 
/* 


new_size; /* 
/* 
/* 


int main(void) { 
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Pointer to an access group */ 
(specifically the PAG in” +*/ 


this example). */ 
Pointer used to loop x*/ 
through each system pointer*/ 
returned by 'matagat'. */ 


The number of objects in +*/ 
the access group. */ 


Loop counter for displaying*/ 
each object pointer in the */ 
Access Group. */ 


Number of bytes required */ 
to hold all information */ 
returned by 'matagat'. */ 


matagat 


tn art a a a te as at nt lion a fa ae nae ns Ra oa ee ereteates Sa */ 
We need to get a pointer to an access group, so 'matpratr' */ 
(Materialize Process Attributes) is used to get a pointer to */ 
the Process Access Group (PAG), which is just a special kind of +*/ 
access group. x/ 
a a at a ail a ta Si te a li iu it */ 

process _attributes.Ptr_Attr3.Template Size = sizeof( MPRT_PTRT ); 

matpratr( &process attributes, NULL, MPRT PAG ); 

access group_ptr = process _attributes.Ptr_Attr3.Mptr_Ptr; 

jr A na it ila hs al Ya kt a ef a rs A i */ 


Call 'matagat' first just to find out how many objects there are +*/ 
in this access group so that we can evaluate the amount of space */ 


required to accommodate information on each of the objects that +*/ 
are part of this access group. The amount of storage required */ 
for the complete fixed-portion of the template will be the exact +*/ 
size of the template. */ 


access group attributes = 
(_MAGAT Template T *) malloc( sizeof( MAGAT Template T ) ); 


access group attributes->Template Size = sizeof(_MAGAT Template T); 


matagat ( access group_attributes, access group ptr ); 


/* output some of the attributes */ 
printf("Characteristics of this access group: \n\n" ); 


printf("Object Name: %30s \n", 
access group attributes->Object_ID.Name ); 


printf("Type and Subtype: %10.4X \n", 
access group attributes->Object_ID.Type Subtype ); 


printf("Access Group Size: %10d \n", 
access group _attributes->Group Size ); 


printf("Available space in the access group: %10d \n", 
access group _attributes->Group Space ); 


printf("Number of objects in the access group: %4d \n", 
access _group_attributes->Object_Count ); 


printf("\n\n"); 
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} 


/eesseeus Geet se ool ee ee eee eos ee ee See eee ees */ 
/* Now that we know exactly how many objects there are, we can */ 
/* determine the amount of space needed to receive all of the */ 
/* information 'matagat' can provide. The additional space required */ 
/* has to accommodate one system pointer for each object in the */ 
/* access group. */ 
/eesee soo See esse ee eee eee eee oe eee eee Soe ee */ 
object_count = access group _attributes->0bject_ Count; 


new_size = sizeof( MAGAT Template_T ) + 
( object_count * sizeof( _SYSPTR ) ); 


access group_attributes = (_MAGAT Template_T *) 
realloc( access _group_ attributes, new_size); 


access group_attributes->Template Size = new_size; 

matagat ( access group attributes, access group ptr ); 

printf("The following are the pointers to the objects that make up\n"); 

printf("the Process Access Group (PAG) for this job. \n\n"); 

object_pointer = &(access group attributes->Object Ptr); 

for ( object=0; object < object_count; object++, object_pointer++ ) { 
printf("System pointer to object %3d is: %p \n", object+l, 


object_pointer ); 


} 


Output 

Characteristics of this access group: 

Object Name: PAG 

Type and Subtype: O1EF 

Access Group Size: 3342336 

Available space in the access group: 1072128 

Number of objects in the access group: 9 

The following are the pointers to the objects that make up 

the Process Access Group (PAG) for this job. 

System pointer to object 1 is: SPP:0000 :laefQPADEVOO25VISCA 003997 


System pointer to object 
System pointer to object 
System pointer to object 
System pointer to object 
System pointer to object 
System pointer to object 
System pointer to object 
System pointer to object 
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is: SPP:0000 :laefQPADEVOOZ25VISCA 003997 
is: SPP:0000 :laefQPADEVOO25VISCA 003997 
is: SPP:0000 :laefQPADEVOO2Z5VISCA 003997 
is: SPP:0000 :laefQPADEVOO2Z5VISCA 003997 
is: SPP:0000 :laefQPADEVOOZ25VISCA 003997 
is: SPP:0000 :laefQPADEVOOZ25VISCA 003997 
is: SPP:0000 :laefQPADEVOOZ25VISCA 003997 
is: SPP:0000 :laefQPADEVOO2Z5VISCA 003997 


OOND ON BWP 


:17bd 
:17be 
:17bf 
:17c0 
:17cl 
:17c2 
:17c3 
:17c4 
217¢5 


matagpat 


Materialize Activation Group Attributes (MATAGPAT) 


Format 
#include <QSYSINC/MIH/MATAGPAT> 


void matagpat (_MAGP_Template_T «receiver, 
unsigned int act_grp_mark, 
char attr_selection); 


Description 
The matagpat function materializes the attributes for the specified activation group 
into the receiver template. 


Parameters 
receiver (input/output) 
Pointer to the receiver template. 


act_grp_mark (input) 
The activation group mark of the activation group whose attributes are to be 
materialized. An activation group mark of zero will materialize the attributes of 
the activation group associated with the current invocation. 


attr_selection (input) 
Specifies the information to be materialized. 


Notes on Usage 
e The builtin function MATAGPAT also provides access to the MI instruction. 
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Example 

This example illustrates the use of the matagpat function. 

/eoesse sos oeee ese eee tse eee coe see eee eee oe oe 
/* 

/* Example Group: Program Execution <QSYSINC/MIH/MATAGPAT> 

/* 

/* Function: matagpat (Materialize Activation Group 

/* Attributes) 

/* 

/* Description: This example uses 'matagpat' to materialize the 

/* name of the root program for the first 

/* activation group in the list of activation 

/* groups for the process. 

/* 

/xepse one ses see pcos ete eee eee eee ee a eee ee eee es 


#include <stdio.h> 

#include <stdlib.h> 

#include <QSYSINC/MIH/MATAGPAT> 
#include <QSYSINC/MIH/MATPRAGP> 
#include <QSYSINC/MIH/MATPTR> 


int main(void) { 


_MPTR_Template_T mpt; 


_MPRAG_Template_T *xMPYgP 

int num_AGs; 
unsigned AG_mark; 

int mpragp_req_size; 
_MAGP_Template_T magp; 

char attr; 


/* Use matpragp to obtain list of AG marks within the process */ 

mprgp = (_MPRAG Template_T *)malloc(sizeof(_MPRAG Template T)); 

mprgp->Template_Size = sizeof(_MPRAG Template _T); 

matpragp (mprgp) ; 

num_AGs = mprgp->Act_Grp_Count; 

mpragp_req_size = sizeof(_MPRAG Template_T) + ((num_AGs - 1)* 
sizeof (unsigned)); 

mprgp = (_MPRAG Template _T *)malloc(mpragp req_size); 

mprgp->Template Size = mpragp_req_size; 

matpragp (mprgp) ; 

AG mark = mprgp->Act_Grp_List[0]; 


/* Materialize the program pointer to the root program of the */ 
/* first AG in the list. */ 
magp.Template Size = sizeof(_MAGP Template _T); 
matagpat (&magp, AG_mark, _MAGP_BASIC_AG_ATTR); 


/* Materialize the program name */ 
mpt.Obj_Ptr.Template Size = sizeof(_OBJPTR_T); 
matptr(&mpt, magp.Data.Basic_Attr.Program) ; 


printf("The root program of AG %u is %.10s\n", AG_mark, 
mpt.Obj_Ptr.Object_ID.Name) ; 


146 = Mi Library Reference 


matagpat 


} 


Output 
The root program of AG 74499 is MATAGPAT 
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Materialize Allocated Object Locks (MATAOL) 


Format 
#include <QSYSINC/MIH/MATAOL> 


void mataol (_MAOL_Template_T *receiver, 
_ANYPTR pointer); 


Description 
The mataol function materializes the current allocated locks on a designated 
system object or space location. 


Parameters 
receiver (input/output) 
Pointer to the receiver template where the materialized locks will be returned. 


pointer (input) 
Pointer to the system object or space location whose allocated locks are to be 
materialized. The argument must be a system pointer or a space pointer. 


Notes on Usage 
e The builtin function MATAOL also provides access to the MI instruction. 


Example 

This example illustrates the use of the mataol function. 

[ees seen se sees e eee ee esse ee sce ee ees see eee ee eee */ 
/* */ 
/* Example Group: Locks <QSYSINC/MIH/MATAOL> x/ 
/* */ 
/* Function: mataol (Materialize Allocated Locks) */ 
/* */ 
/* Description: Use the CL ALCOBJ (Allocate Object) command to */ 
/* place a lock on some object and then use 'mataol' */ 
/* to confirm the lock worked. */ 
/* */ 
/eeeoe ero ose see coe eee ese ee ee ee eee eee ee eee ee */ 


#include <QSYSINC/MIH/MATAOL> 
#include <QSYSINC/MIH/RSLVSP> 
#include <stdio.h> 
#include <stdlib.h> 


/* The receiver template for */ 
_MAOL_Template_T allocated locks; /* 'mataol'. */ 


_SYSPTR some_object; /* The object being locked. x/ 
int main(void) { 


/* Get a pointer to the object. «/ 
some object = rslvsp( _Usrq, "MYUSRQ", "MYLIB", AUTH ALL ); 
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/* Use the CL ALCOBJ command to place a lock on the user queue (this */ 
/* could also be done with the 'lock' function). '‘'mataol' is then */ 
/* used to materialize all of the object locks held for the queue. */ 


system( "ALCOBJ OBJ((MYLIB/MYUSRQ *USRQ *EXCL)) "); 


allocated_locks.Template_ Size = sizeof( MAOL_Template_T ); 


mataol( &allocated_locks, some object ); 


[Roeser eles se see ees Seles selec este tect eee sole esse eee eee eek */ 
/* In order to verify that the Exclusive lock was placed on the */ 
/* object, we can look at the bit pattern returned by 'mataol'. */ 
/* The bit pattern in the first byte (@th element of the array) */ 
/* of 'Lock_Status' represents "Current Cumulative Locks" and x/ 
/* the fifth bit (bit 4) of this field represents the */ 
/* Lock-Exclusive-No-Read (LENR) lock. By using the bitwise AND */ 
/* operator, we can determine if the bit is set by ANDing it with */ 
/* provided bit mask, _LENR_LOCK (which is defined in <milock.h> as */ 
/* hex 08 - bit pattern of 0000 1000). */ 
[Reese sees ee sees ese sesee ees tose ee sept oee ose e se sees esol se */ 


if ( allocated_locks.Lock Status[ 0 ] & _LENR LOCK ) { 
printf("There is an Exclusive-No-Read lock on the object.\n"); 
} 


else 
printf("Error. An Exclusive-No-Read lock is not held on the object.\n"); 


} 
Output 


There is an Exclusive-No-Read lock on the object. 
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Materialize Invocation Attributes (MATINVAT) 


Format 
#include <QSYSINC/MIH/MATINVAT> 


void matinvat (_SPCPTR receiver, 
_INV_Template_T *inv_t, 
int attr_id, 
int rcevr_length); 


Description 

The matinvat function materializes the attributes of the invocation into the receiver 
template. The attributes materialized and the source invocation are specified 
through attr_id and inv_t, respectively. 


Parameters 
receiver (output) 
Pointer to the location to receive the materialized attribute. 


inv_t (input) 
Pointer to the invocation identification template or NULL. Specifying NULL indi- 
cates that the current identification template invocation is to be used for the 
source and originating invocations. 


attr_id (input) 
The attribute identifier. Indicates which attribute of the source invocation is to 
be materialized. 


revr_length (input) 
The length of the receiver. 


Notes on Usage 
e May be used to materialize a single attribute only. 


e The builtin functions MATINVAT1 and _MATINVAT2 also provide access to 
the MI instruction. Use the builtin form to materialize more than 1 attribute. 
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Example 

This example illustrates the use of the matinvat function. 

/ eee Sees espe s eee coe see see te see eee eee eee ce see eee */ 
/* */ 
/* Example Group: Machine Observation <QSYSINC/MIH/MATINVAT> */ 
/* */ 
/* Function: matinvat (Materialize Invocation Attributes) */ 
/* */ 
/* Description: This example uses 'matinvat' to materialize the  +*/ 
/* invocation type of the nearest OPM program in */ 
/* the call stack. Please Note: the 'fndrinvn' and = */ 
/* ‘matinvat' functions themselves have entries on */ 
/* the call stack. This must be taken into account */ 
/* when calculating relative invocation offsets. x/ 
/* This is not necessary if the builtin forms - */ 
/* _MATINVAT1 or _MATINVAT2 and _FNDRINVN1 or */ 
/* _FNDRINVN2 are used. */ 
/* */ 
/#eSse pesos sete eens Sees sett eset eset cee sess sees eect sees */ 


#include <QSYSINC/MIH/MATINVAT> 
#include <QSYSINC/MIH/FNDRINVN> 
#include <string.h> 
#include <stdio.h> 


char srch_arg = _OPM_PROGRAM, inv_type; 
int rel_off; 
_INV_Template_T inv_t; 


int main(void) { 


/* Find relative offset of first OPM program invocation in stack */ 
rel_off = fndrinvn(NULL, _FNDR_RTN_TYPE, &srch_arg, _FNDR_MATCH); 


memset (&inv_t, 0, sizeof(_INV_Template T)); 
inv_t.Inv_Offset = rel_off; /* previous invocation */ 


/* What is the invocation type of this OPM program? */ 
matinvat(&inv_type, &inv_t, MTVA_INV_TYPE, sizeof(inv_type)); 


switch(inv_type) 
{ 
case _CALLX: 
printf("The nearest OPM program is a CALLX\n"); 
break; 
case XCTL: 
printf("The nearest OPM program is a XCTL\n"); 
break; 
case _EVENT_HDLR: 
printf("The nearest OPM program is an event handler\n"); 
break; 
case _OPM_CALLX_HDLR: 
printf("The nearest OPM program is a external exception handler\n"); 
break; 
case PROCESS PROB STATE: 
printf("The nearest OPM program is an IP in problem state\n"); 
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} 


break; 

case _PROCESS_INIT_STATE: 
printf("The nearest OPM program 
break; 

case _PROCESS_TERM_STATE: 
printf("The nearest OPM program 
break; 

case _OPM_INV_EXIT: 
printf("The nearest OPM program 
break; 

case _RETURN: 
printf("The nearest OPM program 
break; 

case _CALLPGM: 
printf("The nearest OPM program 
break; 

default: 
printf("invalid type\n"); 
break; 


Output 
The nearest OPM program is a XCTL 
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an IP in init state\n"); 


an IP in term state\n"); 


an invocation exit\n"); 


a return/XCTL trap handler\n"); 


a CALLPGM\n") ; 


matinxat 


Materialize Independent Index Entries (MATINXAT) 


Format 
#include <QSYSINC/MIH/MATINXAT> 


void matinxat (_IIX_Template_T *receiver, 
_SYSPTR index_obj); 


Description 
The matinxat function materializes the creation attributes and current operational 
statistics of the independent index. 


Parameters 
receiver (input/output) 
Pointer to the receiver template 


index_obj (input) 
Pointer to the independent index whose attributes are to be materialized. 


Notes on Usage 
e The builtin function MATINXAT also provides access to the MI instruction. 


Example 

This example illustrates the use of the matinxat function. 

Jose sesso teense ete see cst ee este cece ec oe eee ese eee ete eee ete */ 
/* */ 
/* Example Group: User Indexes <QSYSINC/MIH/MATINXAT> */ 
/* */ 
/* Function: matinxat (Materialize Index Attributes) */ 
/* */ 
/* Description: Materialize information about the user index. */ 
/* The number of "inserts" made and the number of */ 
/* "finds" done will be displayed to the screen. */ 
/* */ 
/* If entries have been inserted, removed, or search */ 
/* for, then the numbers reported by this program */ 
/* will be nonzero. */ 
/* */ 
Roses sesesseeee sees oss see eect so eee see eee se ec ee eee */ 


#include <QSYSINC/MIH/MATINXAT> 
#include <QSYSINC/MIH/RSLVSP> 
#include <stdio.h> 


/* The receiver template for */ 
_IIX_Template_T index_attributes; /* 'matinxat'. x/ 


_SYSPTR index_ptr; /* Pointer to the user index. */ 


int main(void) { 
/* Get a pointer to the *USRIDX «/ 
index_ptr = rslvsp( _Usridx, "MYUSRIDX", "MYLIB", AUTH ALL ); 
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} 


/* Materialize the attributes of the user index into the receiver 
/* template and output the number of entries inserted, removed and 
/* searched for, as well as the number currently in the user index. 


index_attributes.Template Size = sizeof( _IIX_Template T ); 
matinxat( &index_attributes, index_ptr ); 
printf("Number of entries inserted: ’d \n", 


index_attributes.Count_Insert ); 


printf("Number of entries removed: %d \n", 
index_attributes.Count_Remove ); 


printf("Number of entries currently in the index: %d \n", 
index_attributes.Count_Insert 
- index_attributes.Count_Remove  ); 


printf("Number of find requests: %d \n", 
index_attributes.Count_Find ); 


Output 


Number of entries inserted: 

Number of entries removed: 

Number of entries currently in the index: 
Number of find requests: 
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Materialize Machine Attributes (MATMATR) 


Format 
#include <QSYSINC/MIH/MATMATR> 


void matmatr (_MMTR_Template_T *receiver, 
short attr); 


Description 

The matmatr function makes available the unique values of machine attributes. 
Through the attribute selection value, up to 22 different machine attributes may be 
selected for materialization. 


Parameters 
receiver (input/output) 
Pointer to the materialization template. 


attr (input) 
The attribute selection value. This argument identifies which group of machine 
attributes are to be materialized. 


Notes on Usage 
e The builtin function MATMATR?1 also provides access to the MI instruction. 
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Example 

This example illustrates the use of the matmatr function. 

feoesoe sos oeet esse eee eat see eee eee see see eee ete see eee eee es 
/* 

/* Example Group: Machine Interface <QSYSINC/MIH/MATMATR> 

/* 

/* Function: matmatr (Materialize Machine Attributes) 

/* 

/* Description: Use the 'matmatr' MI function to get back the 

/* CPU Serial Number of the AS/400 on which this 

/* program is run. 

/* 

feeessaesbesesoe eae see sles ee eh ote esse eset eee eb eee eee testes 


#include <QSYSINC/MIH/MATMATR> 
#include <stdio.h> 


/* The receiver template for 
/* 'matmatr'. 


_MMTR_Template_T machine_attributes; 


} 


main(void) { 


The CPU serial number is in the first 16 bytes of the receiver 
template, so only request that 16 bytes of the template are 
materialized. Use the provided flag _MMTR_SERIAL to request the 
"serial number" materialization option. 


machine_attributes.Options.Template Size = 16; 


matmatr( &machine_attributes, _MMTR_SERIAL ); 


printf("Serial Number of this AS/400 is: %8.8s \n", 
machine_attributes.Options.Data.Serial ); 


Output 
Serial Number of this AS/400 is: 1015013 
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Materialize Machine Data (MATMDATA) 


Format 
#include <QSYSINC/MIH/MATMDATA> 


void matmdata (_MDATA_ Template _T «receiver, 
short options); 


Description 
The matmdata function materializes the values of various machine data. 


Parameters 
receiver (output) 
Pointer to the machine data template. 


options (input) 
The machine data options. This argument determines which machine data are 
materialized. The option must be a literal. 


Notes on Usage 
e The builtin function MATMDATA also provides access to the MI instruction. 
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Example 
This example illustrates the use of the matmdata function. 
feoesoe sos oust esse esheets eee ee see shee ee eee eee eee Se */ 
/* */ 
/* Example Group: Machine Interface <QSYSINC/MIH/MATMDATA> */ 
/* */ 
/* Function: matmdata (Materialize Machine Data) */ 
/* */ 
/* Description: ‘matmdata' can be used to determine whether extra */ 
/* checking is done when parameters are passed from +*/ 
/* program to program. This extra checking is done */ 
/* when the system is running with Security Level 50 */ 
/* (C2 Department of Defense Security). */ 
/* */ 
[xeoseon osteo cobs se tee eee eee eee ee eee eee eee */ 
#include <QSYSINC/MIH/MATMDATA> 
#include <stdio.h> 

/* The receiver template for */ 

_MDATA_Template_T machine_data; /* 'matmdata'. */ 
int main(void) { 

/* Materialize only the integrity flag bit setting and store the */ 

/* result in the machine data receiver template. */ 

matmdata( &machine_ data, MDATA_INTEGRITY FLAG ); 
/* Output whether the flag is on or off. */ 


printf("The system Parameter Integrity Validation flag is %s \n", 
machine_data.Integ Flag ? "On" : "Off" ); 


} 


Output 


The system Parameter Integrity Validation flag is Off 
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Materialize Object Locks (MATOBJLK) 


Format 
#include <QSYSINC/MIH/MATOBJLK> 


void matobjlk (_MOBJL_Template_T «receiver, 
_ANYPTR object); 


Description 
The matobjlk function materializes the current lock status of the designated system 
object or space location. 


Parameters 

receiver (input/output) 
Pointer to the receiver template where the materialized lock status will be 
returned. 


object (input) 
Pointer to the system object or space location whose lock status is to be mate- 
rialized. The argument must be a system pointer or a space pointer. 


Notes on Usage 
¢ The builtin function MATOBJLK also provides access to the MI instruction. 


Example 

This example illustrates the use of the matobjlk function. 

/eRosse este cee set ete nt Sete e eee eee eb ee see ee tes cette teste ees eee */ 
/* */ 
/* Example Group: Locks <QSYSINC/MIH/MATOBJLK> */ 
/* */ 
/* Function: matobjlk (Materialize Object Locks) */ 
/* */ 
/* Description: Use the CL ALCOBJ (Allocate Object) command to */ 
/* place a lock on some object. Very much like */ 
/* the 'mataol' example, 'matobjlk' will then be */ 
/* used to verify the lock. */ 
/* */ 
/* ‘matobjlk' returns a little more information than +*/ 
/* 'mataol' in that you can find out whether other */ 
/* jobs/tasks are waiting synchronously or */ 
/* asynchronous for the lock. x/ 
/* */ 
/xeeencese ete essen -te-ee tee ee ee ee eee ee ee eee eee */ 


#include <QSYSINC/MIH/MATOBJLK> 
#include <QSYSINC/MIH/RSLVSP> 
#include <stdio.h> 

#include <stdlib.h> 


/* The receiver template for */ 
_MOBJL_Template_T allocated_locks; /* 'matobjlk'. x/ 


_SYSPTR some_object; /* The object being locked. x/ 


Machine Interface Library Functions 159 


matobjlk 


int main(void) { 
/* Get a pointer to the object. «/ 
some object = rslvsp( _Usrq, "MYUSRQ", "MYLIB", AUTH ALL ); 


/#oseseteen posses ess n eles ees ses ee esate see ten et ee eed ese */ 
/* Use the CL ALCOBJ command to place a lock on the user queue (this */ 
/* could also be done with the 'lock' function). '‘matobjlk' is then */ 
/* used to materialize all of the object locks held for the queue. */ 


/eocbesrasesc see ose See eee sole ee eS occa coe eee tees */ 
system( "ALCOBJ OBJ((MYLIB/MYUSRQ *USRQ *EXCL)) "); 
allocated_locks.Template_ Size = sizeof( MOBJL_Template T ); 


matobjlk( &allocated_locks, some object ); 


/* In order to verify that the Exclusive lock was placed on the */ 
/* object, we can look at the bit pattern returned by 'matobjlk' in */ 
/* the ‘Lock Alloc' field of the template. The fifth bit (bit 4) of  +*/ 
/* this field represents the Lock-Exclusive-No-Read (LENR) lock. By */ 
/* using the bitwise AND (&) operator, we can determine if the bit is */ 
/* set by ANDing it with the provided bit mask, _LENR LOCK (which */ 
/* is defined in <milock.h> as hex 08 - bit pattern 0000 1000). */ 


if ( allocated_locks.Lock_Alloc & _LENR LOCK ) { 
printf("There is an Exclusive-No-Read lock on the object \n"); 
} 
else 
printf("Error. An Exclusive-No-Read lock is not held on the object.\n"); 


} 


Output 


There is an Exclusive-No-Read lock on the object. 
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Materialize Program (MATPG) 


Format 
#include <QSYSINC/MIH/MATPG> 


void matpg (_MATPG_Template_T *receiver, 
_SYSPTR program) ; 


Description 

The matpg function materializes the program into the receiver template. The 
values in the materialization relate to the current attributes of the program. Compo- 
nents of the program template, other than the control information component, may 
not be available for materialization because they were removed with the deletion of 
observability or were absent when the program was created. 


Parameters 
receiver (input/output) 
Pointer to the receiver template. 


program (input) 
Pointer to the program object to be materialized. 


Notes on Usage 
¢ The matpg function can only be used with OPM programs. 


¢ The builtin function MATPG also provides access to the MI instruction. 
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Example 
This example illustrates the use of the matpg function. 


/* Example Group: Program Management <QSYSINC/MIH/MATPG> 
/* Function: matpg (Materialize Program) 


/* Description: This example uses 'matpg' to materialize the 
/* language version/release level of an OPM program. 


#include <stdio.h> 
#include <QSYSINC/MIH/MATPG> 
#include <QSYSINC/MIH/RSLVSP> 
#include <string.h> 
#include <stdlib.h> 


int main(void) { 


_SYSPTR pgm_ptr; 
_MATPG Template T mpg_t; 


memset (&mpg_t, 0, sizeof(_MATPG Template _T)); 


/* Create an OPM program to pass to matpg */ 
system("CRTCLPGM QTEMP/T1520CL1 QCLE/QACLSRC") ; 


pgm_ptr = rslvsp(_Program, "T1520CL1", "QTEMP", AUTH ALL); 


mpg_t.Template Size = sizeof(_MATPG Template T); 
matpg(&mpg_t, pgm_ptr); 


printf("The program was created for version/release: %x\n", 


mpg_t.Lang_ Version); 


} 


Output 


The program was created for version/release: 370 
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Materialize Pointer (MATPTR) 


Format 
#include <QSYSINC/MIH/MATPTR> 


void matptr (_MPTR_Template_T *receiver, 
_ANYPTR pointer); 


Description 
The matptr function returns the materialized form of pointer in the receiver template. 


Parameters 
receiver (input/output) 
Pointer to the receiver template. 


pointer (input) 
The pointer to materialize. May be any one of the ILE pointer types: system 
pointer, space pointer, invocation pointer, procedure pointer, label pointer, or 
suspend pointer. 


Notes on Usage 
e The builtin function MATPTR also provides access to the MI instruction. 


¢ Constants for pointer types are defined in <milib.h>. 
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Example 


This example illustrates the use of the matptr function. 


/* Example Group: 
/* Function: 


/* Description: 


Machine Observation 


<QSYSINC/MIH/MATPTR> 


matptr (Materialize Pointer) 


This example uses 'matptr' to materialize a 
program pointer. 


#include <QSYSINC/MIH/MATPTR> 
#include <QSYSINC/MIH/RSLVSP> 
#include <stdio.h> 


int main(void) { 


_SYSPTR lib_ptr; 
_MPTR_Template_T mpt; 


/* Resolve to program MYPGM in the current library list */ 
lib_ptr = rslvsp(_Program, "MYPGM", "*LIBL", AUTH OBJ MGMT); 
/* Materialize the program pointer */ 


mpt.Obj_Ptr.Template Size = sizeof(_OBJPTR_T); 
matptr(&mpt, lib ptr); 


printf("Object name : %.10s\n", mpt.Obj_Ptr.Object_ID.Name) ; 
printf ("Library : %.10s\n", mpt.Obj_Ptr.Library_ID.Name) ; 
printf ("Type : %x\n", mpt.Obj_Ptr.Ptr_Type); 
printf("Authority  : %u\n", 
mpt.Obj_Ptr.Auth_Or_Off.Ptr_Authorization) ; 


} 

Output 

Object name : MYPGM 
Library : QTEMP 
Type : 1 


Authority : 0 
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Materialize Pointer Locations (MATPTRL) 


Format 
#include <QSYSINC/MIH/MATPTRL> 


void matptr] (_MPTL_Template_T *receiver, 
_SPCPTRCN source, 
int length); 


Description 
The matptrl function finds the pointers in a subset of a space and produces a bit 
mapping of their relative locations. 


The area addressed by the source space pointer is scanned for a length equal to 
that specified in length. A bit in receiver is set for each 16 bytes of source. A bit in 
receiver is set to binary 1 if a pointer exists in the source space, or the bit is set to 
binary 0 if no pointer exists in the source space. 


Bits are set from left to right (bitO, bit1,...) in receiver as the 16-byte areas in source 
are interrogated from left to right. 


Parameters 
receiver (input/output) 
Pointer to the receiver template. 


source (input) 
Pointer to the source area. The area addressed must be 16-byte aligned. 


length (input) 
The length of area to scan. 


Notes on Usage 
e The builtin function MATPTRL also provides access to the MI instruction. 
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Example 
This example illustrates the use of the matptrl function. 


/* Example Group: Machine Observation <QSYSINC/MIH/MATPTRL> 
/* Function: matptrl (Materialize Pointer Locations) 


/* Description: This example uses 'matptrl' to produce a bit map 
/* of pointer locations in the space. 


#include <QSYSINC/MIH/MATPTRL> 
#include <QSYSINC/MIH/RSLVSP> 
#include <stdio.h> 
#include <stdlib.h> 
#include <string.h> 


#pragma linkage(PGMA, 0S) 
void PGMA(void); 

void print_bitmap(void); 
#define SIZE 128 
_MPTL_Template_T mptl; 


int main(void) { 


_SYSPTR pgm_ptr, qtemp_ptr, spc_ptr; 
_SPCPTR source; 
/* Allocate initialized storage for source x*/ 


source = (_SPCPTR)calloc(SIZE, 1); 


/* Produce a bit map of source before storing pointers. x/ 
mptl.Template Size = sizeof(_MPTL Template _T); 
matptr1(&mptl, source, SIZE); 


print_bitmap(); 


/* Resolve to user space MYSPACE in the current library list */ 
spc_ptr = rslvsp(_Usrspc, "MYSPACE", "*LIBL", AUTH NONE); 


/* Store pointers in source at offsets 16, 80 and 112. This */ 
/* will cause bits 1, 5 and 7 (starting with bit 0 on the */ 
/* left) to be set to binary 1 in the resulting bit map. */ 


pgm ptr = (_SYSPTR)PGMA; 
qtemp_ptr = _QTEMP_POINTER; 


memcpy(source + 16, &pgm_ptr, sizeof(pgm_ptr)); 
memcpy(source + 80, &qtemp_ptr, sizeof(qtemp_ptr)); 
memcpy(source + 112, &spc_ptr, sizeof(spc_ptr)); 


/* Produce a bit map of source */ 
matptr1(&mptl, source, SIZE); 
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print_bitmap(); 


} 


void print_bitmap(void) { 


unsigned pos 


=73 


printf("Offset in source 


printf("  @- 15 
(mpt].Locations 
printf(" 16 - 31 
(mpt].Locations 
printf(" 32 - 47 
(mpt].Locations 
printf(" 48 - 63 
(mpt].Locations 
printf(" 64 - 79 
(mpt].Locations 
printf(" 80 - 95 
(mpt].Locations 
printf(" 96 - 111 
(mpt].Locations 
printf(" 112 - 127 
(mpt].Locations 
} 
Output 
Offset in source (bytes) 
0 - 15 
16 - 31 
32 - 47 
48 - 63 
64 - 79 
80 - 95 
96 - 111 
112 - 127 
Offset in source (bytes) 
0 - 15 
16 - 31 
32 - 47 
48 - 63 
64 - 79 
80 - 95 
96 - 111 
112 - 127 


& 


& 


& 


& 


& 


& 


& 


& 


(bytes) 

(1 << pos--)) 
(1 
(1 
(1 


<< 


pos--)) 


<< 


pos--)) 


<< 


pos--)) 


<< 


pos--)) 
<< pos--)) 


pos--)) 


<< 


pos--)) 


matptrl 


Pointer Found\n"); 
%s\n", 

: "No"); 
%s\n", 

: "No"); 
%s\n", 

: "No"); 
%s\n", 

: "No"); 
%s\n", 

: "No"); 
%s\n", 

: "No"); 
%s\n", 

: "No"); 
%s\n\n", 

: "No"); 


2? "Yeas" 


2? "Yas" 


2? "Yas" 


2? "Yas" 


2? "Yeas" 


2? "Yas" 


2? "Yas" 


2? "Yas" 


Pointer Found 


No 


No 
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Materialize Process Activation Groups (MATPRAGP) 


Format 
#include <QSYSINC/MIH/MATPRAGP> 


void matpragp (_MPRAG Template _T *receiver); 


Description 
The matpragp function provides a list of the activation groups which exist in the 
current process. 


Parameters 

receiver (input/output) 
Pointer to the receiver template. The materialization template identified by the 
receiver must be 16-byte aligned in memory. 


Notes on Usage 
¢ A macro version is available. 


e The builtin function MATPRAGP also provides access to the MI instruction. 
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Example 
This example illustrates the use of the matpragp function. 
/ ees sees esses eet eee cee see te see ee pee ee eee see eee */ 
/* */ 
/* Example Group: Process <QSYSINC/MIH/MATPRAGP> */ 
/* */ 
/* Function: matpragp (Materialize Process Activation Groups) */ 
/* */ 
/* Description: This function materializes all of the activation */ 
/* groups associated with the job. Note 'matpragp' +*/ 
/* is called first to find out how many there are so */ 
/* that we can allocate enough space to accommodate */ 
/* all of the information returned by the second */ 
/* call to 'matpragp'. */ 
/* */ 
/#osee reese sees cee pee eee ee eee cee eee ee se eee eee */ 
#include <QSYSINC/MIH/MATPRAGP> 
#include <stdio.h> 
#include <stdlib.h> 

/* Pointer to the receiver */ 
_MPRAG Template T *template; /* template for 'matpragp'. */ 


/* Loop counter for displaying ~*/ 


int actgrp, /* each activation group */ 
/* number. */ 

new_size; /* Number of bytes required x/ 

/* to hold all information */ 

/* returned by 'matpragp'. x/ 


int main(void) { 


[ee seco ee eet e ese ese et see eee eee ese eet eee ese eee tee */ 
/* Call 'matpragp' first just to find out how many activation groups */ 
/* there are in the job/process that is running this program. */ 
/eoessessu ses pest esses setae sche eee ete eect ee cee cease sl */ 


template = (_MPRAG Template_T *) malloc( sizeof(_MPRAG Template_T) ); 
template->Template Size = sizeof( MPRAG Template T ); 
matpragp( template ); 


printf("Number of activation groups associated with this job: %d \n", 
template->Act_Grp_ Count ); 


/* Now that we know exactly how many activation groups there are, */ 
/* we can allocate enough space to accommodate the "variable-length" */ 
/* portion of the template and then call 'matpragp' again to get all */ 
/* of the activation group numbers. Each activation group number is */ 
/* 4-bytes long. */ 


new_size = sizeof(_MPRAG Template T) + (template->Act_Grp Count * 4 ); 
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template = (_MPRAG Template_T *) realloc( template, new_size ); 
template->Template Size = new_size; 


matpragp( template ); 


/eesuasr essences ste eee ee eee ee eee eee eee het eee es */ 
/* Loop through and output each activation group number in an output */ 
/* field of 8 positions. */ 
[eos snessesesese cesses ese ee fe soles eee ose eee ee eee eee ees tl */ 


for (actgrp=0; actgrp < template->Act_Grp Count; actgrpt+ ) { 


printf("%8d \n", template->Act_Grp_List[ actgrp ] ); 


} 
/Rereossenses-secsh pesca Se csh esse see eet Sout e cnet suet ese estes ee */ 
/* You can also see the activation groups by using the CL DSPJOB */ 
/* command (but using 'matpragp' is faster). To call the command */ 
/* from this program you would code the following: */ 
/* — system( "DSPJOB OPTION(*ACTGRP)" ); */ 
/Fesesesscee ese ee ese see se eee cee elt eee eee eee eee ete eee */ 
} 
Output 
Number of activation groups associated with this job: 3 
3977 
2 
1 
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Materialize Process Attributes (MATPRATR) 


Format 
#include <QSYSISNC/MIH/MATPRATR> 


void matpratr (_MPRT Template_T «receiver, 
_SYSPTR control_spc, 
char options); 


Description 
The matpratr function causes either one specific attribute or all the attributes of the 
designated process to be materialized. 


Parameters 
receiver (input/output) 
Pointer to the receiver template. 


control_spc (input) 
The process control space pointer or NULL. A value of NULL indicates that the 
process issuing the instruction is the subject process. 


options (input) 
The materialization options. 


Notes on Usage 
e The builtin functions MATPRATR1 and _MATPRATR2 also provide access to 


the MI instruction. 
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Example 

This example illustrates the use of the matpratr function. 

/eoesse sos oeet esse eee eats eee ees ce ete eee ear ee eee cee oe */ 
/* */ 
/* Example Group: Processes <QSYSINC/MIH/MATPRATR> */ 
/* */ 
/* Function: matpratr (Materialize Process Attributes) */ 
/* */ 
/* Description: This function can return a lot of different */ 
/* information regarding the job/process in which it */ 
/* is run or for some other process. This example */ 
/* shows how to return information on the number */ 
/* of synchronous read and write operations */ 
/* performed by the specified job/process. x*/ 
/* */ 
/xoesee steps tee se pee eh ee eee ce ae ee ee eee eee eee tee */ 


#include <QSYSINC/MIH/MATPRATR> 
#include <stdio.h> 


_MPRT_Template_T process_attributes; /* The receiver template for */ 


/* 'matpratr'. x/ 
int main(void) { 
/eeesnsscsceese lees less et ese esc eee eee ee eee be ese eee es tte */ 
/* Materialize performance information for this job/process (since */ 
/* NULL is used for the second argument of 'matpratr'). */ 
/ eS esos soeee oes tee ee eee eee ee ee ee he eee eee */ 


process _attributes.Scalar_Attr.Template_ Size = sizeof( _MPRT_Template_T ); 


matpratr( &process attributes, NULL, _MPRT PROC PERF ); 


printf("Currently this process has the following number of \n"); 
printf("Reads and Writes: \n\n" ); 


printf("Synchronous Database Reads: d\n", 
process _attributes.Scalar_Attr.Data.Proc_Perf.Num Read DBS ); 


printf("Synchronous Non-Database Reads: %d \n", 
process _attributes.Scalar_Attr.Data.Proc_Perf.Num_Read_NDB S ); 


printf("Total Synchronous Writes (both DB and NDB): 4d \n", 
process attributes.Scalar_Attr.Data.Proc_Perf.Num_Write_S )s 


} 


Output 
Currently this process has the following number of 
Reads and Writes: 


Synchronous Database Reads: 438 


Synchronous Non-Database Reads: 765 
Total Synchronous Writes (both DB and NDB): 1203 
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Materialize Process Locks (MATPRLK) 


Format 
#include <QSYSINC/MIH/MATPRLK> 


void matprlk (_MPRL_Template_T *receiver, 
_SYSPTR pcs); 


Description 

The matprlk function materializes the lock status of the specified process. This 
information identifies each object or space location for which the process has a lock 
allocated or for which the process is in a synchronous or asynchronous wait. 


Parameters 

receiver (input/output) 
Pointer to the receiver template where the materialized lock status will be 
returned. 


pcs (input) 
Pointer to the process control space of the process whose lock status is to be 
materialized or NULL. If NULL is specified, the lock status of the current 
process is materialized. 


Notes on Usage 
e The builtin functions MATPRLK1 and _MATPRLKk2 also provide access to the 
MI instruction. 


Example 

This example illustrates the use of the matprlk function. 

/eoseeeeoe seep ee se st sae se see ese te sue tease sees se eee ese ses eecus */ 
/* x/ 
/* Example Group: Locks <QSYSINC/MIH/MATPRLK> */ 
/* */ 
/* Function: matprlk (Materialize Process Locks) */ 
/* */ 
/* Description: The CL ALCOBJ (Allocate Object) command is used */ 
/* to place a lock on some object. Very much like */ 
/* the 'mataol' and 'matobjlk' examples, we will use */ 
/* ‘matprlk' to materialize and display the locks. ¥*/ 
/* However, unlike the other two functions, 'matprlk'*/ 
/* provides information about all of the objects */ 
/* locked by the job/process that runs this program */ 
/* as opposed to lock information for a particular */ 
/* object. x/ 
/* x/ 
feopeetoee chee Sets e soo eee oe See ete e eee te ee be */ 


#include <QSYSINC/MIH/MATPRLK> 
#include <QSYSINC/MIH/RSLVSP> 
#include <stdio.h> 
#include <stdlib.h> 


_MPRL_Template_T *process_locks; /* Pointer to receiver template.*/ 
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int new_size, /* Number of bytes needed for +*/ 
/* the fixed and variable parts «/ 
/* of the 'matprik' template.  */ 


lock_count; /* Loop counter to loop through «/ 
/* each lock held by the job. +*/ 


int main(void) { 


/eoresee Sesto teerss passa o stesso see Seat sees net ee testes */ 
/* Use the CL ALCOBJ command to place an Exclusive, Allow Read lock +*/ 
/* on a user queue (we could have used 'lock' to place a LEAR lock on */ 
/* the object to accomplish the same thing). */ 
/eesecele see sce e seb seen ese eto see ee eee eee ees */ 


[Roeser o rece see eee ee eee ee eee eee he ete eee ee ee eee tee */ 
/* Have 'matprik' return only the fixed portion of the template since */ 
/* we do not yet know how much space is needed for the variable */ 
/* portion (since it depends on how many locks there are). Using */ 
/* NULL as the second argument (the Process Control Space) will have +*/ 
/* 'matprlk' return lock information for the process/job that is */ 
/* running this program. */ 
/eeerce ooo se ee te eee ee ee eet ee eee ete */ 


process locks = (_MPRL_Template T *) malloc( sizeof(_MPRL_Template T) ); 
process _locks->Template Size = sizeof( MPRL_ Template T ); 


matpr1k( process locks, NULL ); 


/eosessos sess e ees tet Sense eee eee oon eee eee be ee */ 
/* Use the 'Expanded Number of Entries' field from the template to */ 
/* determine the number of object locks the job is holding. */ 
| ee eee ere ea eee ee eee ere */ 


printf("Number of objects that have locks owned by this job/process:"); 
printf("%d \n\n", process_locks->Num Entry Exp ); 


/eeSesebe sce ssee see cel Sees ete le see st tee eee ee ees */ 
/* Now that we know exactly how many locks are held by this job, we */ 
/* can allocate enough space to accommodate the variable-length */ 
/* portion of the template and call ‘matprik' again to have it fill */ 
/* jin all of the information, including the "lock descriptor" */ 
/* information for each lock. */ 
[eee eeeo spe pee et ee Se eee ee se oe Ss eee eee ee ee */ 


new_size = sizeof(_MPRL_Template T) + 
( process_locks->Num Entry Exp * sizeof(_LOCK_Descript_T ) ); 


process locks = (_MPRL_Template T *) realloc( process locks, new_size ); 
process _locks->Template Size = new_size; 


matpr1k( process _locks, NULL ); 


174 = Mi Library Reference 


matprik 


printf("This job/process holds locks to the objects pointed to \n"); 
printf("by the following pointers: \n" ); 


for ( lock_count = 0; 
lock_count < process _locks->Num_Entry_Exp; 
lock_count++ ) { 


printf("Object %3d: pointed to by: %p \n", 
lock_count+1, process_locks->Locks [ lock _count ] ); 


} 


Output 


Number of objects that have locks owned by this job/process: 18 


This job/process holds locks to the objects pointed to 
by the following pointers: 
Object 1: pointed to by: SYP:8100 :Q401QUSRSYS :0:1247 


Object 2: pointed to by: SYP:8100 :Q401QSYS2 :0:1247 
Object 3: pointed to by: SYP:8100 :Q4Q1QHLPSYS :0:1247 
Object 4: pointed to by: SYP:8100 :0401QADM :0:1247 
Object 5: pointed to by: SYP:8100 :04c1QTEMP :0:1247 
Object 6: pointed to by: SYP:8100 :0401QSYS :0:1247 
Object 7: pointed to by: SYP:8100 :Q801VISCA :0:1247 

8 


Object : pointed to by: SYP:8100 :Q401QPDA :0:1247 

Object 9: pointed to by: SYP:0000 :18a0QJOBMSGQ :0:1247 
Object 10: pointed to by: SYP:8100 :1001QPADEV0003 :0:1247 
Object 11: pointed to by: SYP:0401QSYS :1916MAIN :0:1247 
Object 12: pointed to by: SYP:8100 :Q401SALMI :0:1247 

Object 13: pointed to by: SYP:0000 :19dfQMH MESSAGE QUEUE LOCK OBJECT :0:1247 
Object 14: pointed to by: SYP:0401QSYS :1901QDUI80 :0:1247 
Object 15: pointed to by: SYP:8100 :0401QGPL :0:1247 

Object 16: pointed to by: SPP:0401MYLIB :QaQ2MYUSRQ :0:0:1247 
Object 17: pointed to by: SYP:Q401QSYS :1901QSN80 :0:1247 
Object 18: pointed to by: SYP:0401QPDA :1901QDUODSPF :0:1247 
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Materialize Queue Attributes (MATQAT) 


Format 
#include <QSYSINC/MIH/MATQAT> 


void matqat (_MQAT_Template_T *receiver, 
_SYSPTR queue); 


Description 
The matqat function materializes the attributes of the specified queue. 


Parameters 
receiver (input/output) 
Pointer to the receiver template. 


queue (input) 
Pointer to the queue whose attributes are to be materialized. 


Notes on Usage 
e The builtin function MATQAT also provides access to the MI instruction. 


Example 

This example illustrates the use of the matqat function. 

/xepsuesosoese esse pep late e eee cee eae ce eee eee ce * 
/* * 
/* Example Group: User Queues <QSYSINC/MIH/MATQAT> * 
/* * 
/* Function: matgqat (Materialize Queue Attribute) * 
/* * 
/* Description: Materialize the "attributes" of the User Queue * 
/* into a "template" (structure) and output some of * 
/* the returned information to the screen. * 
/* * 
feeos sense se sos se ese See se ese eee se ee eee ose ee ae ee ee eee eel * 


#include <QSYSINC/MIH/MATQAT> 
#include <QSYSINC/MIH/RSLVSP> 
#include <stdio.h> 


_MQAT_Template_T queue_attributes; /* The receiver template for 
/* 'matqat'. 
_SYSPTR queue_ptr; /* Pointer to the user queue. 


int main(void) { 
/* Get a pointer to the *USRQ. 
queue_ptr = rslvsp( _Usrq, "MYUSRQ", "MYLIB", AUTH ALL ); 


/* Materialize the attributes of the user queue and output some of 
/* them to the screen. 
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*/ 
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queue_attributes.Template Size = sizeof( MQAT Template T ); 

matqat( &queue_attributes, queue ptr ); 

printf("Number of entries currently on the queue: %d\n", 
queue_attributes.Num Msgs ); 


printf("Initial number of entries allowed: d\n", 
queue_attributes.Max Msgs ); 


printf("Additional number of entries allowed: d\n", 
queue_attributes.Extension) ; 


printf("Maximum size of any particular entry: %d\n", 
queue_attributes.Max Size ); 

} 

Output 

Number of entries currently on the queue: 3 

Initial number of entries allowed: 10 

Additional number of entries allowed: 50 

Maximum size of any particular entry: 75 
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Materialize Queue Messages (MATQMSG) 


Format 
#include <QSYSINC/MIH/MATQMSG> 


void matqmsg (_MQMS_Template_T *receiver 
_SYSPTR queue, 
char selection, 
int max_key, 
int max_msg, 
_SPCPTR key); 


Description 

The matqmsg function materializes selected messages on a queue. The number of 
messages materialized and the amount of key and message text materialized for 
each message are controlled through the function's parameters. 


Parameters 

receiver (input/output) 
Pointer to the receiver template where the materialized message and attributes 
will be placed. This template must be 16-byte aligned. 


queue (input) 
Pointer to the queue. 


selection (input) 
The message selection criteria. Constants for the allowable values are defined 
in the header file. 


max_key (input) 
The number of key bytes to materialize. It must be a multiple of 16. 


max_msg (input) 
The number of message text bytes to materialize. It must be a multiple of 16. 


key (input) 
Pointer to the message key. This must be a null-terminated string or consist of 
exactly 256 bytes. 


Notes on Usage 
e The builtin function MATQMSG provides access to the MI instruction. 
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Example 

This example illustrates the use of the matqmsg function. 

/ ees Sees esses eet eee cee ee see te ee eee pee eee eee eee */ 
/* */ 
/* Example Group: User Queues <QSYSINC/MIH/MATQMSG> */ 
/* */ 
/* Function: matqmsg (Materialize Queue Messages) x/ 
/* */ 
/* Description: Materialize selected messages from a user queue. */ 
/* */ 
Roos snes e ose eee cate select ec estes e ee eee te ee eee ee ee */ 
#include <QSYSINC/MIH/MATQMSG> 

#include <QSYSINC/MIH/RSLVSP> 

#include <stdio.h> 

#include <string.h> 

#include <stdlib.h> 

#include <stddef.h> 


_MQMS_Template_T *queue_messages; 


char 


_SYSPTR 


int 


char 


*this message data; 


queue_ptr; 


message, 


key_length = 0, 


message _ length = 80, 


new_size; 


*key = il a 


int main(void) { 


/* 
/* 


/* 
/* 


/* 


/* 
/* 


/* 
/* 


/* 
/* 
/* 


/* 
/* 
/* 


/* 
/* 


The pointer to the receiver */ 


template for 'matqmsg'. */ 
Pointer used to loop */ 
through each message. x/ 


Pointer to the user queue. */ 


Loop counter for looping */ 
through each message. x/ 


Not materializing by key so */ 
set the key length to 0. x*/ 


Even though the message sizex/ 
is 75, this value must be a */ 
multiple of 16, so use 80. +*/ 


Number of bytes needed for */ 
both the fixed and variable */ 
portion of the template. */ 


Not a keyed User Queue so */ 
this key will not be used. +*/ 


/* Get a pointer to the *USRQ. */ 

queue_ptr = rslvsp( Usrq, "MYUSRQ", "MYLIB", AUTH ALL ); 
/Reseese sso eee ees else ete eee ee eee ee ee ete */ 
/* Allocate just enough space for the fixed portion of the receiver */ 
/* template. Then call 'matqmsg' to fill in the template with */ 
/* information about all of the messages on the queue. */ 
/eocs sete sete sous et esos eee she cote sees ee eee bees eee eee se */ 


queue_messages = (_MQMS Template T *) 


malloc( sizeof( MQMS Template T ) ); 


queue_messages->Template Size = sizeof( MQMS Template T ); 
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matqmsg ( queue_messages, queue ptr, MQMS ALL, 
key_length, message length, key ); 


printf("Number of messages materialized: %d\n", 
queue_messages->Mat_Msgs ); 


printf("Number of messages on the queue: d\n", 
queue_messages->Num Msgs ); 


printf ("Maximum message size: d\n", 
queue_messages->Max_ Size ); 


Now that we know exactly how many messages there are, we can 
allocate enough space to accomodate the variable-length portion 
of the template providing us with information about each message. 
Since this is a "fixed-message-length" user queue, we know the 
size of each "message" will be the fixed size + the number of 
bytes required for the other fields in _MQMS Data_T. 


new_size = sizeof(_MQMS Template T) + 
( queue_messages->Num Msgs * 
( sizeof (_MQMS Data_T) + queue _messages->Max_ Size ) 


queue_messages = (_MQMS Template T *) 
realloc( queue messages, new size ); 
queue_messages->Template Size = new size; 


matqmsg( queue_messages, queue_ptr, _MQMS ALL, 
key_length, message length, key ); 


Output each message that was returned to us in the storage area 
pointed to by ‘queue _messages'. ‘Message Data' is the first byte 
of the first message structure (_MQMS Data_T). 'this_message_data' 
pointer will be used to access the actual message in this 
structure. The pointer is then moved through all of the 
subsequent message data structures to access the queued messages. 
Since the MQMS Data_T structure only has one byte for the message 
we have to add the length of the message to reset the pointer to 
the next message data structure. Even though the message length 
is 75 bytes, we have to round up to a 16-byte boundary, so we use 
80 as the message length. To get to the next message in the next 
message data structure, we also need to add the offset at which 
the 'Message' member is defined within the _MQMS Data_T structure. 


this_message data = &(queue_messages->Message Data) + 
offsetof( MQMS Data_T, Message ); 


matqmsg 


for ( message=0; message < queue_messages->Mat_ Msgs; messagett+ ) { 
printf("Message %3d: %.75s\n", message+1, this message data ); 


this message data += 80 + offsetof( MQMS Data_T, Message ); 


} 
} 


Output 

Number of messages materialized: 2 

Number of messages on the queue: 2 

Maximum message size: 75 

Message 1: This is the first message being entered. 
Message 2: This is the second message being entered. 
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Materialize Resource Management Data (MATRMD) 


Format 
#include <QSYSINC/MIH/MATRMD> 


void matrmd (_MATRMD_ Template_T *receiver, 
_SPCPTR control); 


Description 
The matrmd function materializes the resource management data. 


Parameters 

receiver (input/output) 
Pointer to the receiver template where the resource management data will be 
materialized. 


control (input) 
Pointer to the 8-byte character control data. This argument identifies the type 
of information to be materialized. 


Notes on Usage 
¢ A macro version is available. 


e The builtin function MATRMD also provides access to the MI instruction. 


Example 

This example illustrates the use of the matrmd function. 

[eee sesese ste Soce see sees Leta eee te se eee eee eee esses */ 
/* */ 
/* Example Group: Resource Management Data(RMD) <QSYSINC/MIH/MATRMD> */ 
/* */ 
/* Function: matrmd (Materialize Process RMD ) */ 
/* */ 
/* Description: This simple example illustrates the use of */ 
/* "matrmd' to get the number of Auxillary Storage */ 
/* Pools (ASPs) and the number of Allocated Auxillary */ 
/* Units attached to the AS/400 on which this program */ 
/* is run. */ 
/* */ 
feececesus ast ese tee ete ee ce eee o see scenes bots ee */ 


#include <QSYSINC/MIH/MATRMD> 
#include <stdio.h> 
#include <stdlib.h> 


/* Pointer to the receiver */ 
_MATRMD_Template_T *RMD_template; /* template for 'matrmd'. x/ 
/* The control option that tells*/ 
char control[ 8 ]; /* 'matrmd' what information */ 
/* should be returned. */ 


int main(void) { 
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Rosato ote ease eee ee oe soe eee ee See ee eee */ 
/* Call 'matrmd' to get the number of Auxillary Storage Pools (ASPs) +*/ 
/* and the number of allocated auxillary storage units. This */ 
/* information is contained in the first 32 bytes of the template */ 
/* so there is no need to materialize the whole thing. */ 
/eesessos esses one se ee sel eee see eee eee eee eee tees ee see */ 


control[ 0 ] = _MATRMD AUX STORAGE; 

RMD_template = ( MATRMD Template T * ) malloc( 32 ); 

RMD_template->Template_Size = 32; 

matrmd( RMD template, control ); 

printf("Number of Auxillary Storage Pools (ASPs): %3d \n", 
RMD_template->_MATRMD_Data.Aux_Storage.Num_ASP ); 

printf("Number of Allocated Auxillary Storage Units: %3d \n", 


RMD_template->_MATRMD_Data.Aux_Storage.Num_Alloc_Aux ); 
} 


Output 
Number of Auxiliary Storage Pools (ASPs): 1 
Number of Allocated Auxiliary Storage Units: 8 
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Materialize Space Attributes (MATS) 


Format 
#include <QSYSINC/MIH/MATS> 


void mats (_SPC_Template_T *receiver 
_SYSPTR space_object); 


Description 
The mats function materializes the current attributes of the space object into the 
receiver template. 


Parameters 

receiver (input/output) 
Pointer to the template where the attributes of the space object are material- 
ized. 


space_object (input) 
Pointer to the space object whose attributes are to be materialized. 


Notes on Usage 
e The builtin function MATS also provides access to the MI instruction. 
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Example 

This example illustrates the use of the mats function. 

/ eee Se eh es soe es eee eco eos ee see te Se eee ee eee eee ce eee eee 
/* 

/* Example Group: Space Management <QSYSINC/MIH/MATS> 

/* 

/* Function: mats (Materialize Space Attributes) 

/* 

/* Description: This example uses 'mats' to materialize the 

/* size of a space object. (Note that the size is 

/* always at least as large as requested and a power 
/* of two.) 

/* 

/xeeeeeees sees sneer ee ee ee ee eee eee eee eee 
#include <stdio.h> 


#i 
#i 
#i 
#d 
in 


{ 


} 


O 
Th 


nclude <QSYSINC/MIH/MATS> 
nclude <QSYSINC/MIH/RSLVSP> 
nclude <QSYSINC/H/QUSCRTUS> 


efine CREATION SIZE 65500 
t main(void) 
_SPC_Template_T space_t; 
_SYSPTR ptr_to_space; 
int error_code = 0; 
QUSCRTUS("MYSPACE  QTEMP m 
"MYSPACE ", 
CREATION SIZE, 
"\o" ; 
"SALL are 
"MYSPACE example for Programmer's Reference ; 
"*YES ca 
&error_code); 
ptr_to space = rslvsp(_Usrspc, "MYSPACE", "QTEMP", AUTH OBJ MGMT) ; 
space t.TmpSize = sizeof(_SPC Template T); 


mats(&space_t, ptr_to_space); 


printf("The actual size of MYSPACE is %d bytes\n", space _t.Size); 


utput 
e actual size of MYSPACE is 65536 bytes 
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Materialize Selected Locks (MATSELLK) 


Format 
#include <QSYSINC/MIH/MATSELLK> 


void matsellk (_MSLL_Template_T *receiver, 
_ANYPTR pointer); 


Description 
The matsellk function materializes the locks held by the process issuing this instruc- 
tion for the object or space location specified. 


Parameters 
receiver (input/output) 
Pointer to the receiver template where the materialized locks will be returned. 


pointer (input) 
Pointer to the system object or space location whose locks are to be material- 
ized. The argument must be a system pointer or a space pointer. 


Notes on Usage 
¢ The builtin function MATSELLK also provides access to the MI instruction. 


Example 

This example illustrates the use of the matsellk function. 

[eesseen se see ee se ete see eee ste ec eee eset eee eee eee */ 
/* x*/ 
/* Example Group: Locks <QSYSINC/MIH/MATSELLK> */ 
/* */ 
/* Function: matsellk (Materialize Selected Locks) */ 
/* */ 
/* Description: Use the CL ALCOBJ (Allocate Object) command to */ 
/* place a lock on some object. Very much like */ 
/* the 'mataol' and 'matobjlk' examples, ‘'matsellk' */ 
/* will be used to verify the lock. x/ 
/* x*/ 
|/xeecreooSossceo se See eats eee oe ce see ae ee ee eee eet */ 


#include <QSYSINC/MIH/MATSELLK> 
#include <QSYSINC/MIH/RSLVSP> 
#include <stdio.h> 

#include <stdlib.h> 


/* The receiver template for */ 
_MSLL_Template_T allocated_locks; /* 'matsellk'. */ 


_SYSPTR some_object; /* The object being locked. x/ 


int main(void) { 
/* Get a pointer to the object. «/ 
some object = rslvsp( _Usrq, "MYUSRQ", "MYLIB", AUTH ALL ); 
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/* Use the CL ALCOBJ command to place a lock on the user queue (this */ 

/* could also be done with the 'lock' function). ‘matobjlk' is then */ 

/* used to materialize all of the object locks held for the queue. */ 
system( "ALCOBJ OBJ((MYLIB/MYUSRQ *USRQ *EXCL)) "); 


allocated_locks.Template Size = sizeof( MSLL Template T ); 


matsellk( &allocated_locks, some object ); 


/eosetee Soho se esos eee se eee ee ee cee ee ee ee eee ee */ 
/* In order to verify that the Exclusive lock was placed on the */ 
/* object, we can look at the bit pattern returned by 'matsellk'. */ 
/* The 'Cum_Lock_Status' field in the template is the bit pattern x/ 


/* that represents the "Current Cumulative Locks" and the fifth bit § */ 
/* (bit 4) of this field represents the Lock-Exclusive-No-Read (LENR) */ 
/* lock. By using the bitwise AND (&) operator, we can determine if */ 
/* the bit is set by ANDing it with the provided bit mask, _LENR_LOCK */ 
/* (which is defined in <milock.h> as hex 08 - bit pattern 0000 1000) .*/ 


if ( allocated_locks.Cum_Lock Status & _LENR LOCK ) { 
printf("There is an Exclusive-No-Read lock on the object \n"); 
} 


else 
printf("Error. An Exclusive-No-Read lock is not held on the object.\n"); 


} 


Output 


There is an Exclusive-No-Read lock on the object. 
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Format 
#include <QSYSINC/MIH/MATSOBJ> 


void matsobj (_MSOB Template_T *receiver, 
_SYSPTR object); 


Description 
The matsobj function materializes the identity and size of a system object. 


Parameters 
receiver (input/output) 
Pointer to the receiver template. 


object (input) 
Pointer to the system object whose attributes are to be materialized. 


Notes on Usage 


e The builtin function MATSOBJ also provides access to the MI instruction. 


Example 
This example illustrates the use of the matsobj function. 


/* Example Group: Machine Observation <QSYSINC/MIH/MATSOBJ> 
/* Function: matsobj (Materialize System Object) 


/* Description: This example uses 'matsobj' to determine if 
/* program SAMPLE is an ILE program. 


#include <QSYSINC/MIH/MATSOBJ> 
#include <stdio.h> 
#include <stdlib.h> 


#pragma linkage (SAMPLE, 0S) 
void SAMPLE(void); 


int main(void) { 
_MSOB_Template_T msob_template; 


/* Create an ILE C program called SAMPLE. */ 
system("CRTBNDC QTEMP/SAMPLE QCLE/QACSRC") ; 


msob_template.Template Size = sizeof(_MSOB Template _T); 
matsobj(&msob_template, SAMPLE); 


/* Is SAMPLE an ILE program? x/ 
printf("SAMPLE is an %s program\n", 
(msob_template.Pgm Type ? "ILE" : "OPM")); 
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Output 
SAMPLE is an ILE program 
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Materialize Time-of-Day Clock (MATTOD) 


Format 
#include <QSYSINC/MIH/MATTOD> 


void mattod (_MI Time time_of_day); 


Description 
The mattod function materializes the time of day clock. 


Parameters 
time_of_day (output) 
An 8-byte character array into which the time-of-day clock is materialized. 


Notes on Usage 
e A macro version is available. 


e The builtin function MATTOD also provides access to the MI instruction. 
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Example 

This example illustrates the use of the mattod function. 

/ dese Sees ss eee eee soos ee see te eee eee eee eee see eee */ 
/* */ 
/* Example Group: Machine Interface <QSYSINC/MIH/MATTOD> */ 
/* */ 
/* Function: mattod (Materialize Time-Of-Day) */ 
/* */ 
/* Description: Use the 'mattod' MI function to get the current */ 
/* MI Time-Of-Day (TOD) value. The function returns */ 
/* an 8-byte value represented by the type MI Time */ 
/* (defined in <milib.h>) which represents a large */ 
/* "counter" in which bit 41 (starting at offset 0) +*/ 
/* is incremented approximately once every */ 
/* millisecond (1/1000th of a second). The TOD is */ 
/* returned by several MI functions and is also used */ 
/* (as input) by other MI functions. x/ 
/* */ 
/eose pesos sate ee eee lh sales see tes pete suet spss edb sesh eee se eel ek */ 


#include <QSYSINC/MIH/MATTOD> 
#include <stdio.h> 


_MI_Time time_of_day; 
int byte; /* Counter for looping through */ 


/* each byte of the MI Time. */ 
int main(void) { 


/eercsee ne eee eee Sees eee eee ee ee eee eee eee ete sete ee eee */ 
/* Materialize the time of day clock and output it to the screen. x/ 
/* Since _MI_Time is an 8-byte character array, we have to loop */ 
/* through each byte and display it as a hexadecimal number. */ 
[Reee as sses sess syst sonst see shee te suse ese eee ee eos ee ete see */ 


mattod( time_of_day ); 


printf("Time of Day returned by 'mattod' in the MI Time format: "); 


for ( byte=0; byte < sizeof(_MI Time); byte++) 
printf("%2.2X", time_of day[ byte ] ); 


printf("\n"); 
} 


Output 
Time of Day returned by 'mattod' in the MI_Time format: 748D3E7FEB400017 
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Machine Interface Time (MITIME) 


Format 

#include <QSYSINC/MIH/MICOMMON> 

_MI_TIME *mitime (_MI_Time *receiver, int hours, 
int minutes, int seconds, int hundredths); 


Description 

The mitime function takes, as parameters, hours, minutes, seconds, and hun- 
dredths of seconds, and converts them to the AS/400 system value for time which 
has the data type _MI_Time. Many of the MI library functions use this _Ml_Time 
data type. 


Parameters 

receiver(output) 
Pointer to an 8-byte character array which is to receive the system value for the 
specified time. 


hours(input) 
The number of hours to be converted to the system value for time. 


minutes(input) 
The number of minutes to be converted to the system value for time. 


seconds(input) 
The number of seconds to be converted to the system value for time. 


hundredths(input) 
The number of 1/100 seconds to be converted to the system value for time. 


Notes on Usage 
e The maximum system time that can be input to mitime is such that the total 
number of hours, minutes, seconds and hundredths of seconds specified must 
not exceed (UINT_MAX * 1024 / 1,000,000) seconds which is about 50 days. If 
this value is exceeded, the results from mitime are undefined. 


Example 
This example illustrates the use of the mitime function. 
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/eeseobee eee eee eet eee eee ee oes Soe eee ees eee ees 
/* 

/* Example Group: Job Information <QSYSINC/MIH/MICOMMON> 

/* 

/* Function: mitime (convert time to AS/400 system value 

/* for time) 

/* Description: Use the 'mitime' MI function to convert 

/* specific values for the components of time to 

/* the AS/400 system value for time. Then use the 

/* formatted MI Time value to suspend or make 

/* the job go to sleep for the specified amount 

/* of time. 

/* 

feos sete ehee ee see eee eee ee See eee oe eee te ee eee 


#include <QSYSINC/MIH/MICOMMON> 
#include <QSYSINC/MIH/WAITTIME> 
#include <stdio.h> 


i 


_MI_Time time_to_wait; /* The amount of time to wait. 
nt hours = 0, /* Time components used to 
minutes = 6, /* create an MI Time value 
seconds = 15, /* that can be passed to the 
hundredths = 0; /* ‘waittime' function 


short wait_option; 


i 


} 


nt main(void) { 


/* Format an 'mitime' value to represent the amount of time to wait. 
/* When 'waittime' is called, the job that is running this program 
/* will be suspended. 


mitime( &time_to_ wait, hours, minutes, seconds, hundredths ); 
/* Tells the system to use normal 


wait_option = _WAIT_NORMAL; /* handling of a suspended job. 


waittime( &time_to_ wait, wait_option ); 
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*/ 


*/ 
*/ 
*/ 
*/ 


-*/ 
*/ 
*/ 
*/ 

-*/ 


*/ 
*/ 
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Output 


** no output ** 
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Modify Automatic Storage Allocation (MODASA) 


Format 
#include <QSYSINC/MIH/MODASA> 


_SPCPTR modasa (unsigned int size); 


Description 

The modasa function extends the size of the automatic storage frame (ASF) 
assigned to the invocation of the currently executing program. The function returns 
the address of the first byte of the ASF extension. This extension might not be 
contiguous with the original allocation. 


Parameters 
size (input) 
The size of the adjustment. This value must be greater than 0. 


Notes on Usage 
¢ A macro version is available. 


e The builtin function MODASA also provides access to the MI instruction. 
e The _MODASA builtin is non-resumable following an exception. 


e If an attempt is made to resume execution without first changing the resume 
point, an MCH2204 is signalled. 
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Example 
This example illustrates the use of the modasa function. 
/eoesse sos oeet ese eee tse eee coe sce see eae eee eee ee one oe 
/* 
/* Example Group: Program Execution <QSYSINC/MIH/MODASA> 
/* 
/* Function: modasa (Modify Automatic Storage Area) 
/* 
/* Description: This simple example shows how the automatic 
/* storage frame (ASF) can be extended. 
/* 
feRoeseasece se sees ese steer epee ee eee ese eee ee eee eee ee esate 
#include <QSYSINC/MIH/MODASA> 
#include <string.h> 
/* The size by which to extend 
int additional bytes = 2000; /* the automatic storage frame. 
char «ptr; /* A pointer that will be set 
/* to the location of the first 


int main(void) { 
ptr = modasa( additional bytes ); 
strcpy( ptr, "Some string" ); 


} 
Output 


** no screen output ** 
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Modify Independent Index (MODINX) 


Format 
#include <QSYSINC/MIH/MODINX> 


void modinx (_SYSPTR index_obj, 
char mod_option); 


Description 
The modinx function modifies the selected attributes of the independent index. 


Parameters 
index_obj (input) 
Pointer to the independent index object whose attributes are to be modified. 


mod_ option (input) 
The modification option. The valid values are: 
0 = No immediate update 
1 = Immediate update 


Notes on Usage 
e The builtin function MODINX also provides access to the MI instruction. 


Example 

This example illustrates the use of the modinx function. 

/#ocseescee seve esses see cee Soe cee seek se eee eee eee eee ee */ 
/* */ 
/* Example Group: User Indexes <QSYSINC/MIH/MODINX> */ 
/* */ 
/* Function: modinx (Modify Index) */ 
/* */ 
/* Description: This example illustrates the use of the Modify */ 
/* User Index function. The only attribute of the */ 
/* index that can be selected for modification is */ 
/* the "immediate update" attribute. If this bit */ 
/* is set, the user index object is written to */ 
/* auxiliary storage on any change to the entries */ 
/* in the user index. */ 
/* */ 
[Reser ssss see sees eae ses eee sete suse eset sets ee os ees ee seats */ 


#include <QSYSINC/MIH/MODINX> 
#include <QSYSINC/MIH/RSLVSP> 
#include <QSYSINC/MIH/MATINXAT> 
#include <stdio.h> 

#include <string.h> 


_IIX_Template_T index_template; 


_SYSPTR index_ptr; /* Pointer to the user index */ 


/* The index attributes returned by 'matinxat' will be copied into */ 
/* the following structure of bit-fields so that the single bit we */ 
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/* want to check is readily available by name. x*/ 


struct index_attributes { 


int entry_type 1 /* Fixed or Variable-length entries*/ 
int when_updated 1s /* Whether or not Immediate Update */ 
int insert_type 1; /* Keyed or Sequential inserts ? */ 
int type_of_data : 1; /* Contain pointers or not ? x/ 
int optimize zc Ts /* Optimized for Random/Sequential */ 
int reserved 3; /* 3 bits unused */ 


} index_attributes; 


#define IMMEDIATE_UPDATE 1 
#define NO IMMEDIATE UPDATE 0 


int main(void) { 
/* Get a pointer to the *USRIDX. */ 
index_ptr = rslvsp( _Usridx, "MYUSRIDX", "MYLIB", AUTH ALL ); 


[Roe See cee eee eos ete ee oe ee eee eee ee eee eee eee */ 
/* Materialize the index attributes and store the "attribute" */ 
/* settings (8-bits). Check the "immediate update" bit (the second § +*/ 
/* bit-field in the structure as shown in the 'index_attributes' */ 
/* structure above) and turn it on to represent the “immediate update"*/ 
/* option if it is not already set. */ 
/eosetest ae esses ee see ees sees eee esate cnet ene cee ce se */ 


index_template.Template Size = sizeof( _IIX_Template_T ); 


matinxat( &index_template, index_ptr ); 


/* Copy the 1-byte attribute field into a structure of bit-fields so */ 
/* we can isolate the “immediate update" flag by name (rather than */ 
/* using the logical AND (&) operator with a bit mask). */ 


memcpy( &index_attributes, &index_template.Attributes, 1 ); 


if ( index_attributes.when_updated != IMMEDIATE_UPDATE ) { 


/* Since the user index did not */ 

/* have the "immediate update" */ 

/* attribute, modify it. x/ 
modinx( index_ptr, IMMEDIATE_UPDATE ); 


printf("The user index attributes were modified so that any \n"); 
printf("update (eg: entry inserts or removals) will cause the \n"); 
printf("index to be written to auxiliary storage. \n"); 
} 
else { 
printf("The user index already had the ‘immediate update' \n"); 
printf("option set on. \n"); 


} 
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Output 

The user index attributes were modified so that any 
update (e.g. entry inserts or removals) will cause the 
index to be written to auxiliary storage. 
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Modify Space Attributes (MODS) 


Format 
#include <QSYSINC/MIH/MODS> 


void mods (_SYSPTR space_object, 
int size); 


Description 

The mods function modifies the size of the space associated with the system 
object. The current allocation of the space is extended or truncated accordingly to 
match as closely as possible the specified size. The modified space size will be at 
least the size specified. 


Parameters 
space_object (input) 
Pointer to the system object whose associated space size is to be modified. 


size (input) 
Size in bytes to which the space size is to be modified. 


Notes on Usage 
e The functions mods and mods2 provide equivalent semantics as the MODS MI 


instruction. 


e The builtin function MODS also provides access to the MI instruction. 
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Example 
This example illustrates the use of the mods function. 


/* Example Group: Space Management <QSYSINC/MIH/MODS> 
/* Function: mods (Modify Space Attributes) 


/* Description: This example uses 'mods' to increase the size 
/* of a space object. 


#include <stdio.h> 

#include <QSYSINC/MIH/MODS> 
#include <QSYSINC/MIH/MATS> 
#include <QSYSINC/MIH/RSLVSP> 
#include <QSYSINC/H/QUSCRTUS> 
#include <QSYSINC/H/QUSEC> 


#define INCREMENT 4096 
#define CREATION SIZE 65500 


int main(void) 


{ 
_SPC_Template_T space_t; 
_SYSPTR ptr_to_space; 
Qus EC t error_code; 


QUSCRTUS ("MYSPACE QTEMP oe 

"MYSPACE ", 

CREATION SIZE, 

"\o" ; 

"SALL Me 

"MYSPACE example for Programmer's Reference , 
"*VES iN 

&error_code); 


mods 


ptr_to space = rslvsp(_Usrspc, "MYSPACE", "QTEMP", AUTH OBJ MGMT) ; 


space t.TmpSize = sizeof(_SPC Template T); 


mats(&space_t, ptr_to_space); 


printf("The current size of MYSPACE is %d bytes\n", space _t.Size); 


mods(ptr_to_space, INCREMENT + space_t.Size); 


mats(&space_t, ptr_to_space); 


printf("The new larger size of MYSPACE is %d bytes\n", space t.Size); 
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Output 
The current size of MYSPACE is 65536 bytes 
The new larger size of MYSPACE is 69632 bytes 
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Modify Space Attributes - Long Form with Template (MODS2) 


Format 
#include <QSYSINC/MIH/MODS> 


void mods2 (_SYSPTR space_object, 
_SPC_MOD_T *space_t); 


Description 
The mods2 function modifies the attributes of the space associated with the system 
object. 


Parameters 

space_object (input) 
Pointer to the system object whose associated space attributes are to be modi- 
fied. 


space_t (input) 
Pointer to the space modification template that contains a selection of space 
attribute values to be used to modify the attributes of the space. 


Notes on Usage 
e The functions mods and mods2 provide equivalent semantics as the MODS MI 


instruction. 


e The builtin function MODS2 also provides access to the MI instruction. 
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Example 
This example illustrates the use of the mods2 function. 


/* Example Group: Space Management <QSYSINC/MIH/MODS> 
/* Function: mods2 (Modify Space Attributes) 


/* Description: This example uses 'mods2' to re-initialize the 
/* space to blanks. 


#include <string.h> 

#include <QSYSINC/MIH/MODS> 
#include <QSYSINC/MIH/RSLVSP> 
#include <QSYSINC/H/QUSCRTUS> 
#include <QSYSINC/H/QUSEC> 


#define CREATION SIZE 65500 


int main(void) 


{ 

_SPC_MOD_T mod_t; 

_SYSPTR ptr_to_space; 

Qus_EC t error_code; 

QUSCRTUS ("MYSPACE QTEMP Os 
"MYSPACE a 
CREATION SIZE, 
"\o" ; 
"SALL ne 
"MYSPACE example for Programmer's Reference em 
"£VES oe 
&error_code) ; 

/* Resolve to existing space */ 


ptr_to space = rslvsp(_Usrspc, "MYSPACE", "QTEMP", AUTH OBJ MGMT); 


memset (&mod_t, 0, sizeof(_SPC_MOD_T)); 


/* Re-initialize the space to blanks */ 
mod_t.Modify_Init_Val = 1; 
mod_t.Re_Init_Space = 1; 


mod_t.InitCh 0x40; 


mods2(ptr_to_ space, &mod_t); 
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Output 


** no screen output ** 
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Resolve System Pointer (RSLVSP) 


Format 
#include <QSYSINC/MIH/RSLVSP> 


_SYSPTR rslvsp (_OBJ_TYPE_T obj_type, 
_OBJ_NAME obj_name, 
_LIB_NAME lib_name, 
_REQ_AUTH auth) ; 


Description 

The rslvsp function locates an object identified by a symbolic address and stores 
the object's addressability in a system pointer. The symbolic address consists of 
the object type, object name, and library. The system pointer returned by the func- 
tion points to the first object encountered with the designated type/subtype code, 
object name, and library without regard to the authorization currently available to 
the process. 


Parameters 

obj_type (input) 
A member of the enumerated list of object types. The enumeration is supplied 
in the <milib.h> header file. 


obj_name (input) 
A null terminated string specifying the name of the object. 


lib_name (input) 
A null terminated string specifying the name of the library where the object is 
stored. You can specify either a specific name for the library, or the character 
string "*LIBL" (or an empty string), which indicates that the current library list is 
to be searched to find the library where the object is stored. 


auth (input) 
Constructed from supplied bit mask macros in the <milib.h> header file. Pro- 
grams executing in user-domain may not assign authority in the resulting 
system pointer. The value in auth is ignored; authority is set to the not set 
state. Otherwise, the object authority states are set as specified by auth. 


Notes on Usage 
e The function will first resolve to the library. If successful, a resolve to the object 
is made. 


e The builtin functions _RSLVSP1 through _RSLVSP8 also provide access to the 
MI instruction. 
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Example 

This example illustrates the use of the rslvsp function. 

/ #eSe se oh es soe ee ee b ecco see sete bee ee ee eo ee eee ee eee 
/* 

/* Example Group: Pointer/Name Resolution Addressing 

/* <QSYSINC/MIH/RSLVSP> 

/* 

/* Function: rslvsp (Resolve System Pointer) 

/* 

/* Description: This example uses 'rslvsp' to obtain a pointer 
/* to program 'MYPGM' in *LIBL. 

/* 

[eesee sass oesdet cee eee ce eee ee ee eee nese esse eee cess 


#i 
#i 
#i 


in 


} 
O 


nclude <QSYSINC/MIH/RSLVSP> 
nclude <QSYSINC/MIH/MATPTR> 
nclude <stdio.h> 

t main(void) { 


_SYSPTR pgm_ptr; 
_MPTR_Template_T mpt; 


/* Resolve to program MYPGM in the current library list */ 
pgm ptr = rslvsp(_Program, "MYPGM", "*LIBL", _AUTH_OBJ_ MGMT); 
/* Materialize the program pointer */ 


mpt.Obj_Ptr.Template Size = sizeof(_OBJPTR_T); 
matptr(&mpt, pgm_ptr); 


printf("Object name : %.10s\n", mpt.Obj_Ptr.Object_ID.Name) ; 
printf ("Library : %.10s\n", mpt.Obj_Ptr.Library_ID.Name) ; 
printf ("Type : %x\n", mpt.Obj_Ptr.Ptr_Type); 
printf("Authority =: %u\n", 


mpt.Obj_Ptr.Auth_Or_Off.Ptr_Authorization) ; 


utput 


Object name : MYPGM 


Li 


brary : QTEMP 


Type tel 
Authority : 0 


rslvsp 
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Retrieve Computational Attributes (RETCA) 


Format 
#include <QSYSINC/MIH/RETCA> 


unsigned int retca (unsigned int mask); 


Description 
The retca builtin retrieves from the machine and returns the 4-byte value containing 
the selected computational attributes. 


Parameters 

mask (input) 
Selection mask specifying which floating-point computational attributes are to 
be retrieved from the machine. The mask, which must be a literal, is con- 
structed by OR'ing together a combination of the following least significant bits 
of the 4-byte mask. 


Mask Bit Portion of Computational attributes value to load 
from the machine 

x'08' Load the Exception Mask byte 

x'04' Reserved (binary 0) 

x'02' Load the Exception Occurrence byte 

x'01' Load the Rounding Mode byte 


For the format of the computational attributes returned by this builtin see the layout 
of the computation attribute bytes in Figure 1 on page 209. 
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The format of the 4-byte computational attributes is: 


60 31 


byte 0 byte 1 byte 2 byte 3 


00 07 00 07 00 07 00 07 
ow high 
address address 


¢ Byte 0: Exception Mask 


0 = disabled (exception is masked) 
1 = enabled (exception is unmasked) 


Bits Meaning 

0-1 Reserved (binary zero) 

2 Floating-point Overflow 

3 Floating-point Underflow 

4 Floating-point Zero Divide 

5 Floating-point Inexact Result 
6 Floating-point Invalid Operand 
7 Reserved (binary zero) 


e Byte 1: Reserved (binary zero) 
e Byte 2: Exception Occurrence 


0 = exception has not occurred 
1 = exception has occurred 


Bits Meaning 
0-1 Reserved (binary zero) 
2 Floating-point Overflow 


3 Floating-point Underflow 

4 Floating-point Zero Divide 

5 Floating-point Inexact Result 
6 Floating-point Invalid Operand 
7 Reserved (binary zero) 


¢ Byte 3: Computational Mode 


Bits Meaning 

0 Reserved (binary zero) 

1-2 Rounding Mode 
00 Round towards positive infinity 
01 Round towards negative infinity 
10 Round towards zero 
11 Round to nearest 

3-7 Reserved (binary zero) 


Figure 1. Layout of the computational attribute bytes 


Notes on Usage 
e retca is available as a macro only. 
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Example 

This example illustrates the use of the retca macro. 

/eoesse sos oeet ese alse eet oes see ee eee ee */ 
/* */ 
/* Example Group: Computation and Branching <QSYSINC/MIH/RETCA> */ 
/* */ 
/* Function: retca (Retrieve Computational Attributes) */ 
/* */ 
/* Description: This example uses 'retca' to retrieve the */ 
/* "rounding mode" portion of the computational */ 
/* attributes. x*/ 
/* */ 
JeReass noose sas see ese Sees eee ee et ee eee ee eee ee eee eee esate */ 


#include <QSYSINC/MIH/RETCA> 
#include <stdio.h> 


#define POSITIVE_INFINITY 0x00 
#define NEGATIVE_INFINITY 0x20 
#define ZERO 0x40 
#define NEAREST 0x60 


int main(void) { 
unsigned rounding_mode; 
rounding_mode = retca(_SRCA_ROUNDING MODE) ; 


switch (rounding mode) { 
case POSITIVE_INFINITY: 
printf("The current setting is round towards positive infinity\n"); 
break; 
case NEGATIVE_INFINITY: 
printf("The current setting is round towards negative infinity\n"); 
break; 
case ZERO: 
printf("The current setting is round towards zero\n"); 
break; 
case NEAREST: 
printf("The current setting is round towards nearest\n"); 
break; 
default: 
printf("Error: unrecognized setting\n"); 
} 
} 


Output 


The current setting is round towards nearest 
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Remove Independent Index Entry (RMVINXEN) 


Format 
#include <QSYSINC/MIH/RMVINXEN> 


_SPCPTR rmvinxen (_SPCPTR receiver, 
_SYSPTR index_obj, 
_IIX_Opt_List_T *option_list, 
_SPCPTR search_arg); 


Description 

The rmvinxen function removes the specified index entries from the independent 
index and returns these in the receiver. A pointer to the receiver is returned by the 
function. 


Parameters 

receiver (input/output) 
Pointer to the buffer to receive the removed entry or entries. A NULL is not 
supported for this parameter. 


index_obj (input) 
Pointer to the independent index object from which the entry or entries are to 
be removed. 


option_list (input) 
Pointer to the option list template. This template contains additional information 
on the entry or entries to be removed. 


search_arg (input) 
Pointer to the search argument(s). 


Notes on Usage 
e The builtin functions RMVINXEN1 and _RMVINXEN2 also provide access to 
the MI instruction. 
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Example 

This example illustrates the use of the rmvinxen function. 

feoesoe sos oust ese sees e tse eee eee ce ese eee eae eee eee oes */ 
/* */ 
/* Example Group: User Indexes <QSYSINC/MIH/RMVINXEN> */ 
/* */ 
/* Function: rmvinxen (Remove Index Entry) */ 
/* */ 
/* Description: This example illustrates how the 'rmvinxen' */ 
/* function can be used to remove a particular */ 
/* entry from a user index. The entry being */ 
/* removed, will be found using the customer */ 
/* number key. Upon removal from the user index, */ 
/* the entry will be displayed to the screen. x*/ 
/* */ 
/xesse este osapeese cee se ee eee eee see eee Soe eee ee ee eee */ 


#include <QSYSINC/MIH/RMVINXEN> 
#include <QSYSINC/MIH/RSLVSP> 
#include <stdio.h> 


typedef struct Customer Entry { /* The format/layout of each */ 
int customer_number; /* entry on the user index. x/ 
char last_name[ 50 ]; 
char first_name[ 40 ]; 
char phone_number[9]; /* Using phone format: 555-5555 «/ 
} Customer_Entry; 


/* Template used for setting */ 


_IIX_Opt_List_T remove_option; /* options for the "remove". x*/ 
/* Also used as the receiver x*/ 
/* for any returned data. */ 
_SYSPTR index_ptr; /* Pointer to the user index. */ 


/* Buffer to receive any entry */ 
Customer_Entry removed customer; /* that matches our criteria. +*/ 


/* Our criterion is to remove” */ 
int which_customer /* the entry that has this x/ 
= 9999999; /* customer number. */ 
int main(void) { 
/* Get a pointer to the *USRIDX «/ 
index_ptr = rslvsp( Usridx, "MYUSRIDX", "MYLIB", AUTH ALL ); 
remove option.Rule = FIND EQUALS; /* Find a customer number that */ 


/* matches the specified one. */ 


remove option.Arg Length /* The customer search "key" */ 
= sizeof( int ); /* is an integer. */ 
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/* Maximum number of entries x/ 
/* to return that match the */ 
remove option.Occ Count = 1; /* criterion. In this case, x/ 
/* we want to find the one */ 


/* unique entry that has the */ 
/* particular customer number. */ 


[Roce see eee este eee ee eee eo eh se see eee ose eee eee le */ 
/* Remove the entry for this particular customer if it exists in the */ 
/* user index. If the entry was successfully removed, output the */ 
/* entry to the screen. */ 
/eesooe esses ese pon ee eel eee eee etl eee ee oe */ 


rmvinxen( &removed customer, index ptr, &remove option, 
&which_customer) ; 


if (| remove _option.Ret Count == 0) { 


printf("Could not remove the entry for customer number: %d \n", 
which customer ); 
printf("since the entry could not be found in the user index.\n"); 


} 
else { /* an entry was found and removed */ 


printf("The removed entry for customer number %d was:\n", 
which_customer ); 


printf("Customer Name: %s %s \n", removed_customer.first_name, 


removed_customer.last_name  ); 
printf("Phone Number: %s \n", removed _customer.phone_number ); 


} 
} 


Output 

The removed entry for customer number 9999999 was: 
Customer Name: John Smith 

Phone Number: 555-5555 
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Scan with Control (SCANWC) 


Format 
#include <QSYSINC/MIH/SCANWC> 


int scanwc (char *base-locator, 
_SCWC_Control_T *controls, 
char options); 


Description 

The scanwc function scans a base string of single or double-byte characters for 
occurrences of a character value satisfying the criteria in the controls and options 
parameters. 


The scanwc function returns -1 if the scan is unsuccessful. Otherwise, scanwc 
returns a value which is the offset of the character which terminated the scan rela- 
tive to the base string. 


On return from the scan, the base locator is still pointing to the first character in the 
base string. This behavior is different from the SCANWC MI which updates the 
base locator. 


Parameters 
source (input) 
Pointer to the base string to scan. 


controls (input/output) 
Pointer to the controls template which specifies additional information to be 
used to control the scan. 


options (input) 
The option indicators. 


Notes on Usage 
¢ This is a compatibility function to provide the same semantics as the SCANWC 
MI instruction. 


e There is no equivalent to the escape target operand of the SCANWC MI pro- 
vided on this interface. 


Exceptions 
If arguments 1 and 2 do not point to valid storage locations, an MCH3601 or an 
MCH0601 exception will be signalled. 


If any of the input parameters are not valid, an MCH3601 or MCHO601 may be 
signalled. 


Other exceptions possible from this function are: 


MCH0602 - Boundary alignment 

MCH0801 - Parameter Reference Violation 
MCH3402 - Object Destroyed 

MCH3602 - Pointer Type Invalid 

MCH6801 - Object Domain Violation 
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Example 

This example illustrates the use of the scanwc function. 

/ depose eh sss es epee cose see see eee eee eee eee eee */ 
/* */ 
/* Example Group: Computation and Branching <QSYSINC/MIH/SCANWC> = */ 
/* */ 
/* Function: Scanwc (Scan With Control) */ 
/* */ 
/* Description: This example uses 'scanwc' to scan the single- */ 
/* byte base string for a character to which ‘k' */ 
/* is ‘greater than or equal’. */ 
/* */ 
[Resse sas See Stet cee eee ose eee el ee ee eee ee cee ee eel ete eee ee */ 


#include <QSYSINC/MIH/SCANWC> 
#include <string.h> 
#include <stdio.h> 


int main(void) { 


char base[]= "This is the base string"; 
_SCWC_Control_T t; 

int offset; 

char options; 


memset(&t, 0, sizeof(t)); 
t.Start_Scan = 1; 
t.Comp_Char[1] = 'k'; 

t.Base Length = sizeof(base); 

offset = scanwc(base, &t, SCWC_NONMIXED GREATER | _SCWC_NONMIXED_ EQUAL) ; 


printf("The scan was stopped at character %c, offset %d\n", 
base[offset], offset); 


} 


Output 


The scan was stopped at character h, offset 1 
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Set Access State (SETACST) 


Format 
#include <QSYSINC/MIH/SETACST> 


void setacst (_ANYPTR object, 
char state_code, 
int pool_id, 
int space_length); 


Description 

The setacst function specifies the access state (which specifies the desired speed 
of access) that the issuing process has for a set of objects or sub-object elements 
in the execution interval following the execution of the function. 


The specification of an access state for an object momentarily preempts the 
machine's normal management of an object. 


Parameters 
object (input) 
The pointer to object. 


state_code (output) 
The access state code. 


pool_id (input) 
The access pool ID. 


space_length (input) 
The space length. 


Notes on Usage 
e The setacst function performs a single object Set Access State only. You must 
use the _SETACST builtin to perform a multiple object Set Access State. 


e For access states 0x10 and 0x18, the operational object size is returned 
through the template. The template is used on the builtin version only. For this 
reason, it is recommended that the SETACST builtin be used for access 
states 0x10 and 0x18. 


e Amacro version is available. 
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setacst 


This example illustrates the use of the setacst function. 


Example Group: 


Function: 


Description: 


*/ 


Resource Management Data(RMD) <QSYSINC/MIH/SETACST>+/ 


setacst (Set Access State) 


This example uses 'setacst' to "bring" an object 
into main memory asynchronously in order to 
improve the access time to the object (rather 
than have it "page-faulted" into main memory if 
it's not already there). It is not necessary to 
explicitly have the object brought into memory 
since the system will ensure that the object is 
in main memory when it is used. In some cases, 
explicitly moving objects into main memory can 
reduce page faulting and improve performance. 


#include <QSYSINC/MIH/SETACST> 
#include <QSYSINC/MIH/RSLVSP> 


#include <stdio.h> 


_sy 


int 


int main(void) { 


SPTR 


some_object; /* The object that is being put 


pool, 


Size; 


/* into main memory. 


/* Main memory storage pool in 
/* which to put the object. 


/* Number of bytes of the object 
/* to be moved into main memory. 


/* Get a pointer to the object. 


some object = rslvsp( _Usrq, "MYUSRQ", "MYLIB", AUTH ALL ); 


Have the first 64K bytes (arbitrary value for this example) of 
the object brought into main memory asynchronously (moved in by 
a "background" task, so this process/job is not necessarily 
suspended - unlike a synchronous "bring"). 


/* 0 specifies to use the pool 


/* in which the job running this 


/* program is using. 


setacst( some_object, _SETACST_ASYNCH REQ, pool, size ); 
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Output 


** no screen output ** 
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Set Bit in String (SETBTS) 


Format 
#include <QSYSINC/MIH/SETBTS> 


void setbts (_SPCPTR bit_string, 
unsigned int bit_offset); 


Description 
The setbts function sets bit_string as indicated by bit_offset. 


Parameters 

bit_string (input) 
A pointer to bit_string with the bits numbered left to right from 0 to the total 
number of bits in the string minus 1. 


bit_offset (input) 
Indicates which bit of bit_string is to be set, with an offset of zero indicating the 
leftmost bit of the leftmost byte of bit_string. This value must be less than 64k. 


Notes on Usage 
e If the selected bit is beyond the end of the string, or the 
value of bit_offset is greater than or equal to 64k, the result of the 
operation is undefined. 


e A macro version is available. 
e The builtin function SETBTS also provides access to the MI instruction. 
Exceptions 


In some circumstances, if the selected bit is beyond the end of allocated storage, 
an MCH3203 exception may be signalled. 
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Example 

This example illustrates the use of the setbts function. 

/eoesse sos eset ese eee tse eet coe cee eee eee eee oe 
/* 

/* Example Group: Computation and Branching <QSYSINC/MIH/SETBTS> 

/* 

/* Function: setbts (Set Bit in String) 

/* 

/* Description: This example uses 'setbts', 'tstbts', and 

/* ‘clrbts' to set, test, and clear the 17th bit 

/* in the bit string. 

/* 

Jeeassnsese sas see ese Sees eee Sh oe pee eee ee tee eee ee eee esate 


#include <QSYSINC/MIH/SETBTS> 
#include <QSYSINC/MIH/TSTBTS> 
#include <QSYSINC/MIH/CLRBTS> 
#include <stdio.h> 


#define FALSE 0 
#define TRUE !FALSE 


int main(void) { 
unsigned bit_string = 0; 
unsigned offset = 17; 
unsigned flag = FALSE; 
setbts(&bit_string, offset); 


flag = tstbts(&bit_string, offset); 


if (flag) 
printf("The %u'th bit has been set\n", offset); 


clrbts(&bit_string, offset); 


flag = tstbts(&bit_string, offset); 


if ('flag) 
printf("The Zu'th bit has been cleared\n", offset); 
} 
Output 


The 17'th bit has been set 
The 17'th bit has been cleared 


220° Mi Library Reference 


setca 


Set Computational Attributes (SETCA) 


Format 
#include <QSYSINC/MIH/SETCA> 


void setca (unsigned int new value, 
unsigned int mask); 


Description 
The setca builtin sets the computational attributes selected and stores them into the 
machine. 


Parameters 
new_value(input) 
The value which is to be used to update the machine computational attributes. 


mask(input) 
Selection mask specifying which floating-point computational attributes are to 
be set in the machine. The mask, which must be a literal, is constructed by 
ORing together a combination of the following least significant bits of the 4-byte 


mask. 
Mask Bit Portion of Computational attributes value to store in 
the machine 
x'08' Store the Exception Mask byte 
x'04' Reserved (binary 0) 
x'02' Store the Exception Occurrence byte 
x'01' Store the Rounding Mode byte 


For the format of the computational attributes returned by this builtin see the layout 
of the computation attribute bytes in Figure 2 on page 222. 
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The format of the 4-byte computational attributes is: 


00 31 


byte 0 byte 1 byte 2 byte 3 


00 07 00 07 00 07 00 07 
ow high 
address address 


e Byte 0: Exception Mask 


0 = disabled (exception is masked) 
1 = enabled (exception is unmasked) 


Bits Meaning 
0-1 Reserved (binary zero) 
2 Floating-point Overflow 


3 Floating-point Underflow 

4 Floating-point Zero Divide 

5 Floating-point Inexact Result 
6 Floating-point Invalid Operand 
7 Reserved (binary zero) 


e Byte 1: Reserved (binary zero) 
e Byte 2: Exception Occurrence 


0 = exception has not occurred 
1 = exception has occurred 


Bits Meaning 
0-1 Reserved (binary zero) 
2 Floating-point Overflow 


3 Floating-point Underflow 

4 Floating-point Zero Divide 

5 Floating-point Inexact Result 
6 Floating-point Invalid Operand 
7 Reserved (binary zero) 


¢ Byte 3: Computational Mode 


Bits Meaning 

0 Reserved (binary zero) 

1-2 Rounding Mode 
00 Round towards positive infinity 
01 Round towards negative infinity 
10 Round towards zero 
11 Round to nearest 

3-7 Reserved (binary zero) 


Figure 2. Computational attributes 


Notes on Usage 
e setca is available as a macro only. 


e When setca is used to change the computational attributes, it is the program- 
mer's responsibility to save the prior attributes and to restore these on 
abnormal/normal termination. 
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Example 

This example illustrates the use of the setca macro. 

/ eeee Se ee esses es eee cose sete eee eee eee eee See eee */ 
/* */ 
/* Example Group: Computation and Branching <QSYSINC/MIH/SETCA> */ 
/* */ 
/* Function: setca (Set Computational Attributes) */ 
/* */ 
/* Description: This example uses 'setca' to temporarily mask */ 
/* the floating point overflow, underflow, and */ 
/* zero divide exceptions. Please Note: it is the */ 
/* responsibility of the programmer to save and */ 
/* restore any prior attribute settings. */ 
/* */ 
Jeeves eeesse stesso nee eee eee sb eee eee ee eee tee eee */ 


#include <QSYSINC/MIH/SETCA> 

#include <QSYSINC/MIH/RETCA> 

#include <except.h> 

#define NEW ATTRIBUTES 0x02000000 /* Mask the following exceptions: */ 
/* floating point overflow */ 
/* floating point underflow */ 
/* floating point zero divide */ 
/* floating point inexact result*/ 

static void cancel_handler (_CNL_Hndlr_Parms_T *parms) { 


/* Restore the saved exception mask attributes passed to the x*/ 
/* handler through the communications area. x/ 


' setca (*(unsigned *)parms->Com Area, _SRCA EXCEPTION MASK) ; 

int main(void) { 
volatile unsigned int old_attributes; 
/* Save the prior exception mask attributes. */ 
old_attributes = retca(_SRCA_EXCEPTION MASK); 
/* Set the new exception mask attributes. */ 
setca(NEW ATTRIBUTES, _SRCA_EXCEPTION MASK) ; 


/* Set up a cancel handler to restore prior exception mask */ 
/* attributes in the event of a cancellation. */ 


#pragma cancel_handler(cancel_handler, old_attributes) 
/* Floating point computations using new attributes would go here...*/ 


/* Restore the saved exception mask attributes. */ 
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setca(old_attributes, _SRCA_EXCEPTION MASK); 
} 
Output 


** no screen output ** 
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Set System Pointer from Pointer (SETSPFP) 


Format 
#include <QSYSINC/MIH/SETSPFP> 


_SYSPTR setspfp (_ANYPTR pointer); 


Description 
The setspfp function returns a system pointer to the system object addressed by 
pointer. 


If pointer is a system pointer, then a system pointer addressing the same object is 
returned containing the same authority as the input pointer. 


If pointer is a space pointer, then a system pointer addressing the system object 
that contains the associated space addressed by pointer is returned. 


Parameters 
pointer (input) 
A space pointer or system pointer. 


Notes on Usage 
¢ A macro version is available. 


e The builtin function SETSPFP also provides access to the MI instruction. 
Exceptions 
If the pointer argument is not set, an MCH3601 is signalled. If the pointer argu- 


ment is not a space pointer, system pointer, or an open pointer containing a space 
pointer or system pointer, an MCH3602, and an MCH3601 are signalled. 
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Example 

This example illustrates the use of the setspfp function. 

/eoesoe sos eset eset alse eet cee ee see eee eee oe oe */ 
/* */ 
/* Example Group: Space Object Addressing <QSYSINC/MIH/SETSPFP> */ 
/* */ 
/* Function: setspfp (Set System Pointer from Pointer) */ 
/* */ 
/* Description: This example uses 'setspfp' to return a system */ 
/* pointer to the object addressed by both a */ 
/* Space pointer and a system pointer. */ 
/* */ 
Jeeassnsese sas see ese Sees tee ee Sb ost eee eee eset e ee eee eee esate */ 


#include <QSYSINC/MIH/SETSPFP> 
#include <QSYSINC/MIH/RSLVSP> 
#include <stdio.h> 


#include <QSYSINC/H/QUSCRTUS> 
#include <QSYSINC/H/QUSPTRUS> 


#define CREATION SIZE 65536 


int main(void) { 


_SPCPTR myspace_spp; 
_SYSPTR myspace _sysp, Sysp; 
int error_code = 0; 
QUSCRTUS ("MYSPACE QTEMP ", /* Create user space */ 
"MYSPACE ", 
CREATION SIZE, 
"er, 
"SALL au 
"MYSPACE example for Programmer's Reference a 
"EYES ne 


&error_code); 


QUSPTRUS ("MYSPACE QTEMP ", /* Retrieve pointer to user space */ 
&myspace_spp); 


/* Case 1: source pointer is a space pointer */ 


myspace_sysp = rslvsp(_Usrspc, "MYSPACE", "QTEMP", AUTH OBJ MGMT); 
sysp = setspfp(myspace_spp); 


if (sysp != myspace_sysp) 

printf("Case 1 : the pointers are not equal\n"); 
else 

printf("Case 1 : the pointers are equal\n"); 
/* Case 2: source pointer is a system pointer */ 
sysp = setspfp(myspace_sysp); 
if (sysp != myspace_sysp) 


printf("Case 2 : the pointers are not equal\n"); 
else 
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printf("Case 2 : the pointers are equal\n"); 
} 
Output 


Case 1: the pointers are equal 
Case 2 : the pointers are equal 
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Set Space Pointer from Pointer (SETSPPFP) 


Format 
#include <QSYSINC/MIH/SETSPPFP> 


_SPCPTR setsppfp (_ANYPTR pointer); 


Description 
The setsppfp function returns the address of a space object from the source pointer 
specified. 


If the source pointer is a space pointer, the pointer returned is set to the address of 
the leftmost byte of the storage location addressed by the source pointer. 


If the source pointer is a system pointer, the pointer returned is set to address the 
first byte of the space contained in the system object addressed by the system 
pointer. 


Parameters 
pointer (input) 
A space pointer or system pointer. 


Notes on Usage 
¢ Amacro version is available. 


¢ The builtin function SETSPPFP also provides access to the MI instruction. 
Exceptions 
If the source pointer is not set, an MCH3601 is signalled. If the pointer is not a 


space pointer, system pointer, or an open pointer containing a space pointer or 
system pointer, an MCH3602 is signalled. 
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Example 

This example illustrates the use of the setsppfp function. 

/ eee Se eh es sss eee coe see settee eee ec eee eee eee eee */ 
/* */ 
/* Example Group: Space Object Addressing <QSYSINC/MIH/SETSPPFP> */ 
/* */ 
/* Function: setsppfp (Set Space Pointer from Pointer) */ 
/* */ 
/* Description: This example uses 'setsppfp' to obtain a pointer */ 
/* to the leftmost byte of the space addressed by */ 
/* both a space pointer and a system pointer. */ 
/* */ 
[Resse sas See eset cee ese se eee eee ee eee eee tee ee eee eee ee */ 


#include <QSYSINC/MIH/SETSPPFP> 
#include <QSYSINC/MIH/RSLVSP> 
#include <string.h> 

#include <stdio.h> 


#include <QSYSINC/H/QUSCRTUS> 
#include <QSYSINC/H/QUSPTRUS> 


#define CREATION SIZE 65536 


int main(void) { 


_SPCPTR myspace spp, sp; 
_SYSPTR myspace_sysp; 
int error_code = 0; 
QUSCRTUS("MYSPACE QTEMP ", /* Create user space */ 
"MYSPACE a 
CREATION SIZE, 
"\o" ; 
"SALL are 
"MYSPACE example for Programmer's Reference M5 
"*VES ca 


&error_code) ; 


QUSPTRUS ("MYSPACE QTEMP ", /* Retrieve pointer to user space */ 
&myspace_spp); 


/* Case 1: source pointer is a space pointer” */ 
sp = setsppfp(myspace spp); 
if (sp != myspace_spp) 
printf("Case 1 : the pointers are not equal\n"); 
else 
printf("Case 1 : the pointers are equal\n"); 
/* Case 2: source pointer is a system pointer */ 
myspace_sysp = rslvsp(_Usrspc, "MYSPACE", "QTEMP", AUTH OBJ MGMT); 
sp = setsppfp(myspace_sysp); 


if (sp != myspace_spp) 
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printf("Case 2 : the pointers are not equal\n"); 


else 
printf("Case 2 : the pointers are equal\n"); 


} 
Output 


Case 1: the pointers are equal 
Case 2 : the pointers are equal 
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Set Space Pointer Offset (SETSPPO) 


Format 
#include <QSYSINC/MIH/SETSPPO> 


_SPCPTR setsppo (_SPCPTR pointer, 
int offset); 


Description 
The setsppo function takes the value of offset and assigns it to the offset portion 
pointer. The resulting pointer is returned by the function. 


Parameters 
pointer (input) 
The space pointer whose offset is to be set. 


offset (input) 
The space pointer offset value. 


Notes on Usage 
e The resulting space pointer continues to address the same space object. 


¢ pointer is left unchanged. 
Exception 


If the pointer argument is not set, or the offset argument is not valid (too large, or 
negative), an MCH3601 is signalled. 


Machine Interface Library Functions 231 


setsppo 


Example 
This example illustrates the use of the setsppo function. 


/* Example Group: Space Object Addressing <QSYSINC/MIH/SETSPPO> 
/* Function: setsppo (Set Space Pointer Offset) 


/* Description: This example uses 'setsppo' to set the offset 
/* portion of a space pointer. 


#include <stdio.h> 
#include <QSYSINC/MIH/SETSPPO> 
#include <QSYSINC/MIH/STSPPO> 


int main(void) { 
int buffer[50]; 


_SPCPTR spl = buffer + 25, sp2 = buffer; 


sp2 = setsppo(sp2, stsppo(spl)); 
if (spl != sp2) 

printf("Error: the pointers are not equal\n"); 
else 

printf("The pointers are equal\n"); 


} 
Output 


The pointers are equal 


232 = Mi Library Reference 


stsppo 


Store Space Pointer Offset (STSPPO) 


Format 


#i 


in 


nclude <QSYSINC/MIH/STSPPO> 


t stsppo (_SPCPTR pointer); 


Description 
The stsppo function returns the offset value of pointer. 


Parameters 
pointer (input) 


Space pointer to extract offset from 


Exceptions 
If the pointer argument is not set, an MCH3601 is signalled. 


Example 
This example illustrates the use of the stsppo function. 


#i 
#i 


#d 


in 


} 
O 


Example Group: Space Object Addressing <QSYSINC/MIH/STSPPO> 
Function: stsppo (Store Space Pointer Offset) 


Description: This example uses 'stsppo' to return the offset 
value of a space pointer. 


nclude <stdio.h> 
nclude <QSYSINC/MIH/STSPPO> 


efine OFFSET 25 


t main(void) { 
int buffer[50], offsetl, offset2; 


_SPCPTR spl = buffer + OFFSET, sp2 = buffer; 
offsetl = stsppo(spl); 


offset2 = stsppo(sp2); 
printf("offsetl - offset2 = %d bytes\n", offsetl - offset2); 


utput 


offsetl - offset2 = 100 bytes 
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Test Authority (TESTAU) 


Format 
#include <QSYSINC/MIH/TESTAU> 


short testau (_SYSPTR object, 
short offset, 
short req_auth); 


Description 

The testau function returns information on the object authorities and/or ownership 
rights currently available to the process for the object specified. The operation is 
performed relative to the invocation whose offset is specified. 


Parameters 
object (input) 
Pointer to the system object for which authority is to be tested. 


offset (input) 
Identifies an invocation relative to the current at which the authority verification 
is to be performed. 


req_auth (input) 
Indicates the required authority and/or ownership rights to be tested and 
returned by the function (if currently available to the process). 


Notes on Usage 
¢ The builtin function TESTAU1 or _TESTAU2 also provides access to the Ml 


instruction. 

Example 

This example illustrates the use of the testau function. 

[eats croc see see tee pete eee Soe eee eee see eee eee */ 
/* */ 
/* Example Group: Authorizations <QSYSINC/MIH/TESTAU> */ 
/* */ 
/* Function: testau (Test Authorization) */ 
/* */ 
/* Description: This example shows how 'testau' can be used to */ 
/* determine what kind of authority the job in which */ 
/* this program runs in, has to some object. This */ 
/* example determines whether the job can delete or */ 
/* update a particular program object (QCMD *PGM */ 
/* in QSYS). x/ 
/* */ 
feReaess noose sas epee ee see ose cee tee eee eee eee ese eee eee eee eee testes */ 


#include <QSYSINC/MIH/TESTAU> 
#include <QSYSINC/MIH/RSLVSP> 
#include <stdio.h> 
/* Pointer to the object that */ 
_SYSPTR some_object; /* will be tested for certain */ 
/* authority. */ 
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short test_authority, /* Authority being checked. */ 
return_authority, /* Actual authority this job */ 
/* has to the object. x*/ 


relative_invocation; 
int main(void) { 
/* Get a pointer to the object */ 


/* that is being tested. x/ 
some object = rslvsp( Program, "QCMD", "QSYS", _AUTH_NONE ); 


/RoSoUR Soh eee see eee eee eee ee cee ee se eee eee */ 
/* 'testau' will be used to check if the job that is running this */ 
/* program has both delete and update authority to the object. */ 
/#eee ss lce sce s see coe eee oe ee eee see esses eee cee set eee eee */ 


test_authority = AUTH DELETE | _AUTH_UPDATE; 


relative_invocation = 0; /* Use the current invocation. */ 


return_authority = testau( some object, relative invocation, 
test_authority ); 


/Roeotee a oe ee sees eee se oe oes oe eee cee eee eee */ 
/* If the actual authority does not match the authority we were */ 
/* testing for, then output this information to the screen. */ 
[eee est ose sae ees eee ese eh eco ce eee eee ce eee se ee set este ee */ 


if ( return_authority != test_authority ) { 


printf("This job/process does not have Delete or Update\n"); 
printf("authority to the QSYS/QCMD program. \n"); 


} 


Output 
This job/process does not have Delete or Update 
authority to the QSYS/QCMD program. 
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Trim Length (TRIML) 


Format 
#include <QSYSINC/MIH/TRIML> 


int trim] (char «string, 
char trim_char); 


Description 
The triml function returns the length of string after trim_char has been trimmed from 
the end. 


trim_char is trimmed from the end of string as follows: if the rightmost (last) char- 
acter of string is equal to the character specified by trim_char, the length of the 
trimmed string is reduced by 1. This operation continues until the rightmost char- 
acter is no longer equal to trim_char or the trimmed length is zero. 


string is not changed by this function. 


Parameters 
string (input) 
The source string. 


trim_char (input) 
The trim character. 


Notes on Usage 
e The triml function operates on null-terminated strings. 


e This is a compatibility function to provide the same semantics as the TRIML MI 
instruction. 


Exceptions 
If invalid input values are passed to the function, an MCH3601 and MCHO601 
exception may be signalled. 


Other exceptions possible from this function are: 


MCH0602 - Boundary alignment 

MCH0801 - Parameter Reference Violation 
MCH3402 - Object Destroyed 

MCH3602 - Pointer Type Invalid 

MCH6801 - Object Domain Violation 
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Example 

This example illustrates the use of the triml function. 

/ ees Sees espe s epee cose see see te eee eee eee eee eee ee eee */ 
/* */ 
/* Example Group: Computation and Branching <QSYSINC/MIH/TRIML> */ 
/* */ 
/* Function: triml (Trim Length) */ 
/* */ 
/* Description: This example uses 'triml' to return the length */ 
/* of the string after the trim character '!' has */ 
/* been removed. */ 
/* */ 
[Resse sass Stet cee eee eo ce eee ee ee see eee eee cee eee eee ete eee ee */ 


#include <QSYSINC/MIH/TRIML> 
#include <string.h> 
#include <stdio.h> 


int main(void) { 


char trim_str[] = "String with lots of punctuation! !!!!!irrri'; 
int trim_len; 
trim_len = triml(trim_str, '!'); 


printf("The length of the untrimmed string is %d\n", strlen(trim_str)); 
printf("The length of the trimmed string is %d\n", trim_len); 


} 


Output 
The length of the untrimmed string is 42 
The length of the trimmed string is 31 
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Test Bit in String (TSTBTS) 


Format 
#include <QSYSINC/MIH/TSTBTS> 


int tstbts (_SPCPTR bit_string, 
unsigned int bit offset); 


Description 

The tstbts function tests the bit in bit_string, as indicated by bit_offset, to determine 
if the bit is set or not set. The tstbts function returns a nonzero value if the 
selected bit is set; otherwise zero is returned. 


Parameters 

bit_string (input) 
Pointer to bit_string with the bits numbered left to right from 0 to the total 
number of bits in the string minus 1. 


bit_offset (input) 
Indicates which bit of bit_string is to be tested with an offset of O indicating the 
leftmost bit of the leftmost byte of bit_string. This value must be less than 64k. 


Notes on Usage 
e If the selected bit is beyond the end of the string, or the value 
of bit_offset is greater than or equal to 64k, the result of the operation 
is undefined. 


e A macro version is available. 
e The builtin function TSTBTS also provides access to the MI instruction. 
Exceptions 


In some circumstances, if the selected bit is beyond the end of allocated storage, 
an MCH3203 exception may be signalled. 
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Example 

This example illustrates the use of the tstbts function. 

/ eeSe Sees espe s eee coe es see see eee eee eee eee ee ece eee */ 
/* x/ 
/* Example Group: Computation and Branching <QSYSINC/MIH/TSTBTS> = */ 
/* */ 
/* Function: tstbts (Test Bit in String) */ 
/* */ 
/* Description: This example uses 'setbts', 'tstbts', and */ 
/* "clrbts' to set, test, and clear the 17th bit */ 
/* in the bit string. */ 
/* */ 
[Resse sass ee stat cee eee se eee eee eee eee cee ee ee eee eee ee */ 


#include <QSYSINC/MIH/TSTBTS> 
#include <QSYSINC/MIH/SETBTS> 
#include <QSYSINC/MIH/CLRBTS> 
#include <stdio.h> 


#define FALSE 0 
#define TRUE !FALSE 


int main(void) { 
unsigned bit_string = 0; 
unsigned offset = 17; 
unsigned flag = FALSE; 
setbts(&bit_string, offset); 


flag = tstbts(&bit_string, offset); 


if (flag) 
printf("The Zu'th bit has been set\n", offset); 


clrbts(&bit_string, offset); 
flag = tstbts(&bit_string, offset); 


if ('flag) 
printf("The Zu'th bit has been cleared\n", offset); 


} 


Output 
The 17'th bit has been set 
The 17'th bit has been cleared 
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Unlock Object (UNLOCK) 


Format 
#include <QSYSINC/MIH/UNLOCK> 


void unlock (_SYSPTR object, 
char unlock_option, 
char lock_state); 


Description 
The unlock function releases a single lock for the system object specified. 


Parameters 
object (input) 
Pointer to the system object to be unlocked. 


unlock_option (input) 
The unlock option specifies if locks are to be released or outstanding lock 
requests are to be cancelled. 


lock_state (input) 
The lock state to unlock. 


Notes on Usage 
¢ The lock entry will always be marked as active by the unlock function. So, for 
the function version it is not necessary to OR the lock state with 
_LOCK_ENTRY_ACTIVE. 


¢ The builtin function UNLOCK and macro Unlock also provide access to the MI 
instruction. 
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Example 

This example illustrates the use of the unlock function. 

jeep sees esses eee be ce eeo see see oe ee eee ec ee ee eee see eee */ 
/* */ 
/* Example Group: Locks <QSYSINC/MIH/UNLOCK> */ 
/* */ 
/* Function: unlock (Unlock Object) */ 
/* */ 
/* Description: This example illustrates the use of the ‘unlock’ */ 
/* function. The 'lock' function will first be used */ 
/* to place a Shared Read (LSRD) lock on the object = +*/ 
/* (a user queue in this example). The CL DSPJOB */ 
/* command will then be used to display all of the */ 
/* locks held by the job/process that runs this */ 
/* program. After using the 'unlock' function to */ 
/* remove the lock, DSPJOB is used again to allow */ 
/* the user to verify that the lock was removed. */ 
/* */ 
/#eSse pesos eee een sl see see eet es ote suet ses oesb sete ese se seul se */ 


#include <QSYSINC/MIH/UNLOCK> 
#include <QSYSINC/MIH/RSLVSP> 
#include <QSYSINC/MIH/LOCK> 
#include <stdio.h> 

#include <stdlib.h> 


_SYSPTR some_object; /* The object being locked. x/ 
_MI_Time timeout; /* Amount of time to wait for */ 
/* the lock to be placed. x*/ 

int hours = 0, /* Time components used to */ 
minutes = 0, /* create an MI Time value x/ 

seconds = 20, /* that can be passed to the */ 

hundredths = 0; /* 'lock' function. */ 


int main(void) { 


/* Get a pointer to the object ~*/ 
some object = rslvsp( _Usrq, "MYUSRQ", "MYLIB", AUTH ALL ); 


/Rose person ases see S ee eee ee eee se eee eee eee pe occ eee */ 
/* Format an 'mitime' value to represent the timeout to be used by */ 
/* the 'lock' function when trying to obtain a Shared-Read (LSRD) */ 


/* lock on the object. If the lock request cannot be satisfied in the */ 

/* specified amount of time, then an exception will be raised. The */ 

/* CL DSPJOB command is called to display all of the object locks */ 

/* owned by the job/process that runs this program. */ 
mitime( &timeout, hours, minutes, seconds, hundredths ); 


lock( some_object, timeout, _LSRD LOCK ); 


system( "DSPJOB OPTION(*JOBLCK)" ); 
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/eeeeee see ee ese eee eeeee e eee cee ee eee eee eee es */ 
/* Now the ‘unlock! function is used to remove the LSRD lock and the */ 
/* object locks for the job are displayed again. */ 
/Resesstepeese sees sel sate esse et esos seep ese Seen ee ee eet e soe */ 
unlock( some_object, _UNLOCK_SPECIFIC, _LSRD LOCK ); 
system( "DSPJOB OPTION(*JOBLCK)" ); 
} 
Output 
Display Job Locks 
System: = TORAS4YL 
Job: OMXNA3S4 User: VISCA Number: 009616 
Job status: ACTIVE 
Type options, press Enter. 
5=Display job member locks 
Object Member 
Opt Object Library Type Lock Status Locks 
MAIN QSYS *MENU * SHRNUP HELD 
* SHRNUP HELD 
MYUSRQ MYLIB *USRQ *SHRRD HELD 
OMXNA3S4 QSYS *DEVD *EXCLRD HELD 
*EXCLRD HELD 
*EXCLRD HELD 
*EXCLRD HELD 
QADM QSYS *LIB *SHRRD HELD 
More... 
F3=Exit F5=Refresh F10=Display job record locks F12=Cancel 
Display Job Locks 
System: = TORAS4YL 
Job: OMXNA3S4 User: VISCA Number: 009616 
Job status: ACTIVE 
Type options, press Enter. 
5=Display job member locks 
Object Member 
Opt Object Library Type Lock Status Locks 
MAIN QSYS *MENU *SHRNUP HELD 
* SHRNUP HELD 
OMXNA3S4 QSYS *DEVD *EXCLRD HELD 
*EXCLRD HELD 
*EXCLRD HELD 
*EXCLRD HELD 
QADM QSYS *LIB *SHRRD HELD 
More... 
F3=Exit F5=Refresh F10=Display job record locks  F12=Cancel 
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Unlock Space Location (UNLOCKSL) 


Format 
#include <QSYSINC/MIH/UNLOCKSL> 


void unlocks] (_SPCPTR location, 
char lock state); 


Description 
The unlocksl function removes a single lock type from the space location. 


Parameters 
location (input) 
Pointer to the space location to be unlocked. 


lock_state (input) 
The lock state to unlock. 


Notes on Usage 
e The builtin functions UNLOCKSL1 and _UNLOCKSL2 also provide access to 
the MI instruction. 


¢ The _UNLOCKSL2 builtin supports multiple space location unlock requests. 
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Example 
This example illustrates the use of the unlocks! function. 
/eoesoe sos oeet esse eee tse ee coe ce eee eee ee eee eee 
/* 
/* Example Group: Locks <QSYSINC/MIH/UNLOCKSL> 
/* 
/* Function: unlocks] (Unlock Space Location) 
/* 
/* Description: Place an Exclusive-No-Read (LENR) on a particular 
/* byte (space location) of some object (a user 
/* queue in this example). This type of lock is 
/* "symbolic" in that it does not prevent the space 
/* location from being referenced or updated. 
/* 
[xeoseee poses oee cose ete eee eee eee eee ee ee ee ee eee eee 
#include <QSYSINC/MIH/UNLOCKSL> 
#include <QSYSINC/MIH/RSLVSP> 
#include <QSYSINC/MIH/LOCKSL> 
#include <QSYSINC/MIH/SETSPPFP> 
#include <QSYSINC/MIH/MATOBJLK> 
#include <stdio.h> 
/* The object from which some 
_SYSPTR some_object; /* byte (space) location will 
/* locked. 
_SPCPTR some_byte; /* The pointer to the location 
/* that is being locked. 
/* The receiver template used 
_MOBJL_Template_T allocated_locks; /* by 'matobjlk'. 


int main(void) { 
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Ss 


/* 
/* 
/* 
/* 


] 


/* Get a pointer to the object 
ome object = rslvsp( Usrq, "MYUSRQ", "MYLIB", AUTH ALL ); 


/* Set a space pointer from 
/* the system pointer. 
ome_byte = setsppfp( some object ); 


Request the Exclusive-No-Read (LENR) lock on the space location. 

A default timeout called the "Process Default Timeout" is used as 
the timeout value. If the lock request is not satisfied in that 

time, an exception is raised. 


ocks1( some_byte, _LENR LOCK ); 


*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 


*/ 
*/ 


*/ 


unlocksl 


/eoeoue ote sete eee ee eo Soe sce see ee ee */ 
/* In order to verify that the Exclusive lock was placed on the space */ 
/* location (byte), we can look at the bit pattern returned by */ 


/* ‘'matobjlk' in the 'Lock_Alloc' field of the template. The fifth */ 
/* bit (bit 4) of this field represents the Lock-Exclusive-No-Read */ 
/* (LENR) lock. By using the bitwise AND (&) operator, we can */ 
/* determine if the bit is set by ANDing it with the provided bit */ 
/* mask, _LENR_LOCK (which happens to be defined in <milock.h> as x/ 
/* hex 08 which is bit pattern 0000 1000). */ 


allocated_locks.Template Size = sizeof( MOBJL_ Template T ); 


matobjlk( &allocated_locks, some byte ); 


if ( allocated_locks.Lock_Alloc & _LENR_LOCK ) { 


printf("There is an Exclusive-No-Read lock on the space \n"); 
printf("location with address: %p \n\n", some byte ); 


/* For illustration purposes, we will now remove the lock we */ 
/* just placed on the space location and use 'matobjlk' again */ 
/* to verify that it gets removed. */ 


printf("The lock will now be removed... \n"); 
unlocks1( some_byte, _LENR LOCK ); 
matobjlk( &allocated_locks, some byte ); 


/* If the LENR bit is still set */ 
if ( allocated _locks.Lock_Alloc & _LENR LOCK ) 


printf("Error. The LENR lock still exists.\n"); 
else 
printf("The LENR lock was removed. \n"); 
} 
} 


Output 

There is an Exclusive-No-Read lock on the space 

location with address: SPP:0401MYLIB :QaQ02MYUSRQ :0:0:d35 
The lock will now be removed... 

The LENR lock was removed. 
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Wait on Time (WAITTIME) 


Format 
#include <QSYSINC/MIH/WAITTIME> 


void waittime (_MI_Time *wait_interval, 
short options); 


Description 

The waittime function causes the current process to be placed in a wait state for 
the amount of time specified by the wait interval in accordance with the specified 
wait options. 


Parameters 
wait_interval (input) 
Pointer to an 8-byte time interval prepared using the mitime function. 


options (input) 
The wait options. 


Notes on Usage 
e The builtin function WAITTIME also provides access to the MI instruction. 
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Example 

This example illustrates the use of the waittime function. 

/ eeSe Se eh ess sees eet c oes ee see te eee eee eee ce see eee 
/* 

/* Example Group: Processes <QSYSINC/MIH/WAITTIME> 

/* 

/* Function: waittime (wait or sleep for a specified time) 
/* 

/* Description: This example shows how you can suspend or make 

/* your job go to sleep for a specified amount of 

/* time. This is similar to the CL DLYJOB (delay 

/* job) command. 

/* 

Jee ecee see tees ents ee ee ee ee ee ee ee eee eee eee 


#include <QSYSINC/MIH/WAITTIME> 
#include <stdio.h> 


j 


_MI_Time time_to_wait; /* The amount of time to wait. 

int hours = 0, /* Time components used to 
minutes = 6, /* create an MI Time value 
seconds = 15, /* that can be passed to the 
hundredths = 0; /* ‘waittime' function 


short wait_option; 


i 


} 


nt main(void) { 


/* Format an 'mitime' value to represent the amount of time to wait. 
/* When 'waittime' is called, the job that is running this program 
/* will be suspended. 
mitime( &time_to_wait, hours, minutes, seconds, hundredths ); 
/* Tells the system to use normal 


wait_option = _WAIT_NORMAL; /* handling of a suspended job. 


waittime( &time_to_ wait, wait_option ); 


** no output ** 
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*/ 


247 


xfrlock 


Transfer Object Lock (XFRLOCK) 


Format 
#include <QSYSINC/MIH/XFRLOCK> 


void xfrlock (_SYSPTR process, 
_SYSPTR object, 
char lock_state_to_transfer); 


Description 

The xfrlock function allocates a single lock to the receiving process. Upon com- 
pletion of the transfer request, the current process no longer holds the transferred 
lock. 


Parameters 
process (input) 
Pointer to the receiving process control space. 


object (input) 
Pointer to the system object whose lock is to be transferred. 


lock_state_to_transfer (input) 
Identifies the lock state to be transferred to the receiving process. 


Notes on Usage 
¢ The lock entry will always be marked as active by the xfrlock function. So, for 
the function version, it is not necessary to OR the lock state with 
_LOCK_ENTRY_ACTIVE. 


¢ The builtin function _XFRLOCK, which supports multiple lock transfer requests, 
also provides access to the MI instruction. 
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Example 

This example illustrates the use of the xfrlock function. 

jeeps ete esses eee b eee ee See see Ste ee eee cee ee ses */ 
/* */ 
/* Example Group: Locks <QSYSINC/MIH/XFRLOCK> */ 
/* */ 
/* Function: xfrlock (Transfer Object Lock) */ 
/* */ 
/* Description: This example shows how the job/process in which */ 
/* this program is run can obtain an object lock */ 
/* and then transfer it to another job. In order */ 
/* to transfer the lock, the Process Control Space x/ 
/* (PCS) of the other job/process needs to be known. */ 
/* */ 
/* One way to accomplish this would be for an ILE */ 
/* C/400 program running in another job to use the */ 
/* ‘matpratr' (materialize process attributes) */ 
/* function to obtain the PCS pointer. This pointer */ 
/* could then be put into a User Space or onto a */ 
/* User Queue. This program would then have to */ 
/* resolve to the User Space or User Queue and get */ 
/* the PCS pointer. The pointer could then be copied */ 
/* into the 'to_PCS' variable defined in this program */ 
/* to pass to the 'xfrlock' function. */ 
/* */ 
/* In order to not complicate this example too much, */ 
/* the 'to_PCS' variable will be filled in with the +*/ 
/* Process Control Space of the job/process that */ 
/* runs this program. This effectively means that */ 
/* the lock is not being transferred to another */ 
/* job, but this example should still illustrate the */ 
/* use of the 'xfrlock' function. */ 
/* */ 
/eese esses Sane es set sans e see ees ee suse ese tee eee os eee sone sao. */ 


#include <QSYSINC/MIH/XFRLOCK> 
#include <QSYSINC/MIH/RSLVSP> 
#include <QSYSINC/MIH/LOCK> 
#include <QSYSINC/MIH/MATPRATR> 
#include <stdlib.h> 


_SYSPTR some_object; /* The object being locked. x/ 
_SYSPTR to_PCS; /* Process Control Space (PCS) */ 
/* (job) that the lock will be */ 
/* transferred to. x/ 
_MI_Time timeout; /* The amount of time to wait */ 


/* for the lock to be placed. */ 


int hours = 0, /* Time components used to */ 
minutes = 0, /* create an MI_Time value */ 
seconds = 3, /* that can be passed to the’ */ 
hundredths = 0; /* ‘lock' function */ 


/* The receiver template for */ 
_MPRT_Template_T process_attributes; /* the call to 'matpratr' to */ 
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/* get the PCS pointer. */ 


int main(void) { 


/* Get a pointer to the object.*/ 
some object = rslvsp( _Usrq, "MYUSRQ", "MYLIB", _AUTH_ALL ); 


| ee ae ee ee a eee eee */ 
/* Format an 'mitime' value to represent the timeout to be used by */ 
/* the 'lock' function when trying to obtain an Exclusive-No-Read */ 


/* (LENR) lock on the object. If the lock request cannot be satisfied */ 
/* in the specified amount of time, then an exception will be raised. */ 
/* The CL DSPJOB command is called to display all of the object locks */ 
/* owned by the job/process that runs this program. */ 
mitime( &timeout, hours, minutes, seconds, hundredths ); 


lock( some_object, timeout, _LENR LOCK ); 


system( "DSPJOB OPTION(*JOBLCK)" ); 


/eeresee ene es seuss Sessa Secs eos se see ote ou ese se ee eee eee esee ce Coes */ 
/* Obtain the PCS of the job/process that is running this program */ 
/* by using the Materialize Process Attributes function with the */ 
/* PCS selection option. x/ 
feecsssce senses ete ee epee eee eee ee eee eee cee ee eee */ 


process _attributes.Ptr_Attr3.Template Size = sizeof( MPRT_PTRT ); 
matpratr( &process attributes, NULL, MPRT CTRL SPC ); 


to_PCS = process _attributes.Ptr_Attr3.Mptr_Ptr; 


[ee seeco secon see e tee se eeu see ese rs eee ee se eee ee es */ 
/* Now transfer the LENR lock on the object to the other job. DSPJOB «/ 
/* will be used again to allow the user to verify that the lock */ 
/* disappears from this job. Since this example does not really */ 
/* transfer the lock to another job, the lock will still appear on */ 
/* the Display Job Locks display. */ 
/eecbesrssestsse ole ee tee ee eee eee eee so eee ee eee ee eS */ 


xfrlock( to PCS, some object, _LENR_LOCK ); 


system( "DSPJOB OPTION(*JOBLCK)" ); 
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Output 
Display Job Locks 
System: = TORAS4YL 
Job: OMXNA3S4 User: VISCA Number: 009616 
Job status: ACTIVE 


Type options, press Enter. 
5=Display job member locks 


Object Member 
Opt Object Library Type Lock Status Locks 
MAIN QSYS *MENU *SHRNUP HELD 
* SHRNUP HELD 
MYUSRQ MYLIB *USRQ *EXCL HELD 
OMXNA3S4 QSYS *DEVD *EXCLRD HELD 
*EXCLRD HELD 
QADM QSYS *LIB *SHRRD HELD 
More... 


F3=Exit F5=Refresh F10=Display job record locks F12=Cancel 


Display Job Locks 
System: —TORAS4YL 
Job: OMXNA3S4 User: VISCA Number: 009616 


Job status: ACTIVE 


Type options, press Enter. 
5=Display job member locks 


Object Member 
Opt Object Library Type Lock Status Locks 
MAIN QSYS *MENU *SHRNUP HELD 
*SHRNUP HELD 
MYUSRQ MYLIB *USRQ *EXCL HELD 
OMXNA3S4 QSYS *DEVD *EXCLRD HELD 
*EXCLRD HELD 
QADM QSYS *LIB *SHRRD HELD 
More... 


F3=Exit F5=Refresh F10=Display job record locks F12=Cancel 
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Translate with Table (KLATEWT) 


Format 
#include <QSYSINC/MIH/XLATEWT> 


void xlatewt (char *receiver, 
const char *source, 
const char «table); 


Description 

The xlatewt function translates the source characters under control of the translate 
table and places the translated characters into the receiver. The operation begins 
with the leftmost character of the source and proceeds character-by-character, left- 
to-right, until all source characters have been translated. 


Parameters 

revr_string (input/output) 
Pointer to the receiver location to receive the translated string. The resulting 
string will be null-terminated. 


src_string (input) 
The source string. 


table (input) 
Pointer to the translation table. Must be exactly 256 bytes in length. This table 
specifies the translated values for the 256 possible byte values. Results are 
undefined if the table provided is less than 256 bytes. 


Notes on Usage 
e The xlatewt function operates on null-terminated strings. 


e This is a compatibility function with the same semantics as the XLATEWT MI 
instruction. 


e The length of the string to translate must be between 0 and 16 773 104. 


e The builtin function XLATEB also provides access to the MI instruction. 
_XLATEB does the translation in place. 


Exceptions 
If any of the input parameters are invalid, an MCH3601 or MCHO0601 exception may 
be signalled. 


Other exceptions possible from this function are: 


MCH0602 - Boundary alignment 

MCH0801 - Parameter Reference Violation 
MCH3402 - Object Destroyed 

MCH3602 - Pointer Type Invalid 

MCH6801 - Object Domain Violation 
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Example 

This example illustrates the use of the xlatewt function. 

jeep Sees sss eet coe s ee see tt eee cee ec eee eee eee eee */ 
/* */ 
/* Example Group: Computation and Branching <QSYSINC/MIH/XLATEWT> */ 
/* */ 
/* Function: xlatewt (Translate with Table) */ 
/* */ 
/* Description: This example uses 'xlatewt' and a simple */ 
/* "case folding' translate table to change the */ 
/* input string to uppercase. x/ 
/* */ 
[Resse sass oe eset eee ee se ce ee eel ee ce ee eee cee eee ee ete eee ee */ 


#include <QSYSINC/MIH/XLATEWT> 
#include <string.h> 
#include <stdio.h> 


#define SIZE 100 


char xtable[256] = { 
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int main(void) { 


char source[SIZE] = "good day"; 
char receiver[SIZE] ; 


xlatewt(receiver, source, xtable); 
printf("The translated string is %s\n", receiver); 


} 


Output 
The translated string is GOOD DAY 
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Appendix: Reference Summary 


Table 1 briefly describes the MI functions. For each instruction the function proto- 


type and description is provided. 


The prototype for the associated builtin is also provided if it is identical to that of the 
function. The table also provides the prototypes for builtins which do not have a 


function interface. 


The interface type of each function is also identified. The possible interface types 


are: 


Type Description 


Function Provides access to the MI instruction or performs an equivalent function. 


Builtin Provides access to the MI instruction. 


The naming convention for the ILE C/400 MI library functions is as follows: 


e Function names are all lowercase characters, for example, matinvat. 


¢ Builtin names are in uppercase with an initial underscore character, for 


example, _MATS. 


Table 1 (Page 7 of 18). Machine Interface Instructions 


Instruction C Function Prototype Description 
ATIEXIT #include <mipgexec.h> Establish an invocation exit 
Fi i handler by copying 
unction pointers exit_handler and 
int atiexit (_OS_func_t *exit_handler, parm to internal buffers. 
void *parm) 
CDD #include <QSYSINC/MIH/MIDTTM> The date specified by 
F ; date2 is subtracted from 
unction the date specified by date? 
void cdd (_SPCPTR date_duration, and the value of the result 
_SPCPTRCN datel, is placed in date_duration. 
_SPCPTRCN date2, 
_INST_Template_T2 *inst_t); 
Builtin 
void _CDD (_SPCPTR date_duration, 
_SPCPTRCN datel, 
_SPCPTRCN date2, 
_INST_Template_T2 *inst_t); 
CLRBTS #include <QSYSINC/MIH/CLRBTS> Clear the bit in bit_string 
: corresponding to bit_offset. 
Function 
void clrbts (_SPCPTR bit_string, 
unsigned int bit_offset); 
Builtin 
void _CLRBTS (_SPCPTR bit_string, 
unsigned int bit_offset); 
CMPPSPAD #include <QSYSINC/MIH/CMPPSPAD> Compares space address- 


Function 


int cmppspad (_SPCPTR spacel, 
_SPCPTR spaceZ) ; 


ability of space? and 
space2. 


© Copyright IBM Corp. 1996 
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Table 1 (Page 2 of 18). Machine Interface Instructions 


int cmpptra (_ANYPTR pointerl, 
_ANYPTR pointer2) ; 


Builtin 


int _CMPPTRA (_ANYPTR pointerl, 
_ANYPTR pointer2); 


Instruction C Function Prototype Description 
CMPPTRA #include <QSYSINC/MIH/CMPPTRA> The objects addressed by 
, pointer! and pointer2 are 
Function 


compared to determine if 
they are addressing the 
same object. 


CMPPTRT #include <QSYSINC/MIH/CMPPTRT> 


Function 


int cmpptrt (_ANYPTR pointer, 
char type); 


Builtin 


int _CMPPTRT (char type, 
_ANYPTR pointer); 


CPRDATA #include <QSYSINC/MIH/CPRDATA> 


Function 


int cprdata (_SPCPTR result, 
int result_length, 
_SPCPTRCN source, 
int src_length) ; 
Builtin 
void _CPRDATA (_CPRD_Template_T *cprd_t); 


Compares the pointer type 
of pointer with the char- 
acter type. 


Compresses user data of 
specified length. 


CRTMTX #include <QSYSINC/MIH/CRTMTX> 
Builtin 


int _CRTMTX (_Mutex_T *, 
_Mutex_Create_T *); 


Creates a mutex. 


CTD #include <QSYSINC/MIH/MIDTTM> 


Function 


void ctd (_SPCPTR time_duration, 
_SPCPTRCN timel, 
_SPCPTRCN time2, 
_INST_Template_T2 *inst_t); 


Builtin 


void _CTD (_SPCPTR time_duration, 
_SPCPTRCN timel, 
_SPCPTRCN time2, 
_INST_Template_T2 *inst_t); 


The time specified by 
time2, is subtracted from 
the time specified by time1 
and the value of the result 
is placed in time_duration. 


CTSD #include <QSYSINC/MIH/MIDTTM> 


Function 


void ctsd (_SPCPTR timestamp_duration, 
_SPCPTRCN timestampl, 
_SPCPTRCN timestamp2, 
_INST_Template_T2 *inst_t); 


Builtin 


void _CTSD (_SPCPTR timestamp_duration, 
_SPCPTRCN timestampl, 
_SPCPTRCN timestamp2, 
_INST_Template_T2 *inst_t); 


The timestamp specified 
by timestamp2, is sub- 
tracted from the timestamp 
specified by timestamp? 
and the result is placed in 
timestamp_duration. 
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Table 1 (Page 3 of 18). Machine Interface Instructions 


Instruction 


C Function Prototype 


Description 


CVTBC #include <QSYSINC/MIH/CVTBC> Converts source from the 
F : BSC compressed format to 
unction character, under control of 
int cvtbc (_SPCPTR receiver, controls, and places the 
unsigned int rcvr_length, result into receiver. 
_CVTBC_Control_T *controls, 
_SPCPTRCN source, 
unsigned int src_length); 
Builtin 
void _CVTBC (_SPCPTR receiver, 
unsigned int rcvr_length, 
_CVTBC_Control_T *controls, 
_SPCPTRCN source, 
unsigned int src_length, 
int *return_code); 
Return Code 
Value Meaning 
-1 Completed Record 
0 Source Exhausted 
1 Truncated Record 
CVTCB #include <QSYSINC/MIH/CVTCB> Converts source from 
F : character to the BSC com- 
unction pressed format, under 
int cvtcb (_SPCPTR receiver, control of controls, and 
unsigned int rcvr_length, places the result into 
_CVTCB_Control_T *controls, receiver. 
_SPCPTRCN source, 
unsigned int src_length); 
Builtin 
void _CVTCB (_SPCPTR receiver, 
unsigned int rcvr_length, 
_CVTCB_Control_T *controls, 
_SPCPTRCN source, 
unsigned int src_length, 
int *return_code); 
Return Code 
Value Meaning 
-1 Receiver Overrun 
0 Source Exhausted 
CVTCH #include <QSYSINC/MIH/CVTCH> Each 8-bit character of 
F : source is converted to a 
unction 4-bit hex digit and placed 
void cvtch (_SPCPTR receiver, in receiver. 
_SPCPTRCN source, 
int size); 
CVTCM #include <QSYSINC/MIH/CVTCM> Converts source from 


Function 
int cvtcm (_SPCPT 
unsign 
_CVTCM 
_SPCPT 
unsign 
Builtin 
void _CVTCM (_SPC 


unsi 
CVT 


SPC 


unsi 
int 
Return Code 


Value Meaning 


R receiver, 
ed int revr_length, 
Control_T *controls, 


RCN source, 


ed int src_length); 


PTR receiver, 

gned int revr_length, 
CM_Control_T «controls, 
PTRCN source, 

gned int src_length, 
*return_code) ; 


-1 Receiver Overrun 


0 Source Exhausted 


character format to MRJE 
compressed format under 
control of controls, and 
places the results in 
receiver. 


Appendix 


: Reference Summary 


257 


Table 1 (Page 4 of 18). Machine Interface Instructions 


Instruction 


C Function Prototype 


Description 


Function 


void cvthc (_SPCPTR receiver, 
_SPCPTRCN source, 
int size); 


CVTCS #include <QSYSINC/MIH/CVTCS> Converts source from 
F ; character to SNA format 
unction under control of controls, 
int cvtcs (_SPCPTR receiver, and places the results in 
unsigned int rcvr_length, receiver. 
_CVTCS_Control_T *controls, 
_SPCPTRCN source, 
unsigned int src_length); 
Builtin 
void _CVTCS (_SPCPTR receiver, 
unsigned int rcvr_length, 
_CVTCS_Control_T *controls, 
_SPCPTRCN source, 
unsigned int src_length, 
int *return_code); 
Return Code 
Result Meaning 
-1 Receiver Overrun 
0 Source Exhausted 
CVTD #include <QSYSINC/MIH/MIDTTM> The date specified in 
F ; source_date is converted 
unction to another calendar 
void cvtd (_SPCPTR result_date, external or internal presen- 
_SPCPTRCN source_date, tation and placed in 
_INST_Template_Tl *inst_t); result_date. 
Builtin 
void _CVTD (_SPCPTR result_date, 
_SPCPTRCN source_date, 
_INST_Template_Tl *inst_t); 
CVTEFN #include <QSYSINC/MIH/CVTEFN> Scans a character source 
F ; for a valid decimal number 
unction in display format, removes 
int cvtefni (_SPCPTRCN source, the display character, and 
unsigned int src_length, places the result in 
char mask[3]); receiver. 
double cvtefnd (_SPCPTRCN source, 
unsigned int src_length, 
char mask[3]); 
Builtin 
void _CVTEFN (_SPCPTR receiver, 
_DPA_Template_T *rcvr_descr, 
_SPCPTRCN source, 
unsigned int *src_length, 
_SPCPTR mask) ; 
or 
void _CVTEFN1(_SPCPTR receiver, 
_DPA_Template_T *rcvr_descr, 
_SPCPTRCN source, 
unsigned int *src_length, 
_SPCPTR mask) ; 
or 
void _CVTEFN2(_SPCPTR receiver, 
_DPA_Template_T *rcvr_descr, 
_SPCPTRCN source, 
unsigned int *src_length); 
CVTHC #include <QSYSINC/MIH/CVTHC> Each 4-bit hex digit of 


source is converted to an 
8-bit character and placed 
in receiver. 
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Table 1 (Page 5 of 18). Machine Interface Instructions 


Instruction 


C Function Prototype 


Description 


CVTMC #include <QSYSINC/MIH/CVTMC> Converts source from 
Fi : MRJE compressed format 
unction to character format under 
int cvtmc (_SPCPTR receiver, control of controls, and 
unsigned int rcvr_length, places the results in 
_CVTMC_Control_T *controls, receiver. 
_SPCPTRCN source, 
unsigned int src_length); 
Builtin 
void _CVTMC (_SPCPTR receiver, 
unsigned int rcvr_length, 
_CVTMC_Control_T «controls, 
_SPCPTRCN source, 
unsigned int src_length, 
int *return_code); 
Return Code 
Result Meaning 
-1 Receiver Overrun 
0 Source Exhausted 
CVTSC #include <QSYSINC/MIH/CVTSC> Converts source from SNA 
F | format to character format 
unction under control of controls, 
int cvtsc (_SPCPTR receiver, and places the results in 
unsigned int revr_length, receiver. 
_CVTSC_Control_T *controls, 
_SPCPTRCN source, 
unsigned int src_length); 
Builtin 
void _CVTSC (_SPCPTR receiver, 
unsigned int rcvr_length, 
_CVTSC_Control_T *controls, 
_SPCPTRCN source, 
unsigned int src_length, 
int *return_code); 
Return Code 
Result Meaning 
-1 Receiver Overrun 
0 Source Exhausted 
1 Escape Code Encountered 
CVTT #include <QSYSINC/MIH/MIDTTM> The time specified in 
F ; source_time is converted 
unction to another external or 
void cvtt (_SPCPTR result_time, internal presentation and 
_SPCPTRCN source_time, placed in result_time. 
_INST_Template_T1 *inst_t); 
Builtin 
void _CVTT (_SPCPTR result_time, 
_SPCPTRCN source_time, 
_INST_Template_Tl *inst_t); 
CVTTS #include <QSYSINC/MIH/MIDTTM> The timestamp specified in 


Function 


void cvtts (_SPCPTR result_timestamp, 
_SPCPTRCN source_timestamp, 
_INST_Template_Tl *inst_t); 


Builtin 


void _CVTTS (_SPCPTR result_timestamp, 
_SPCPTRCN source_timestamp, 
_INST_Template_Tl *inst_t); 


source_timestamp is con- 
verted to another external 
or internal presentation 
and placed in 
result_timestamp. 
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Table 1 (Page 6 of 18). Machine Interface Instructions 


Instruction C Function Prototype Description 


CPYBLA #include <QSYSINC/MIH/CPYBLA> Copies source to receiver 
(without pad). 


Function 


void cpybla (_SPCPTR receiver, 
_SPCPTRCN source, 
int size); 
Builtin 


void _CPYBYTES (_SPCPTR receiver, 
_SPCPTRCN source, 
unsigned int size); 


CPYBLAP #include <QSYSINC/MIH/CPYBLAP> Copies source to receiver. 
with pad. 


Function 


void cpyblap (_SPCPTR receiver, 
int revr_size, 
_SPCPTRCN source, 
int src_size, 
char pad); 


CPYHEXNN #include <QSYSINC/MIH/CPYHEXNN> The numeric hex digit 
value (rightmost 4 bits) of 
the byte referred to by 
char cpyhexnn (char «dest, char source); source, is copied to the 
numeric hex digit value 
(rightmost 4 bits) of the 
leftmost byte of dest. 


CPYHEXNZ #include <QSYSINC/MIH/CPYHEXNZ> The numeric hex digit 

value (rightmost 4 bits) of 

the byte referred to by 

char cpyhexnz (char «dest, char source); source, is copied to the 
zone hex digit value (left- 
most 4 bits) of the leftmost 
byte of dest. 


CPYHEXZN #include <QSYSINC/MIH/CPYHEXZN> The zone hex digit value 

(leftmost 4 bits) of the byte 

referred to by source, is 

char cpyhexzn (char *dest, char source); copied to the numeric hex 
digit (rightmost 4 bits) of 
the leftmost byte referred 
to by dest. 


CPYHEXZZ #include <QSYSINC/MIH/CPYHEXZZ> The zone hex digit value 
(leftmost 4 bits) of the byte 
referred to by source, is 
char cpyhexzz (char *dest, char source); copied to the zone hex 
digit value (leftmost 4 bits) 
of the leftmost byte 
referred to by dest. 


CPYNV #include <QSYSINC/MIH/CPYNV> Copies the numeric value 
of source to the numeric 
value of receiver, with 
void cpynv (_NUM_Descr_T revr_descr, appropriate conversions. 

_SPCPTR receiver, 

_NUM_Descr_T src_descr, 

_SPCPTRCN source); 


Function 


Function 


Function 


Function 


Function 


Builtin 
void _LBCPYNV (_SPCPTR receiver, 
_DPA_Template_T 
*rcvr_attributes, 
SPCPTRCN source, 
_DPA_Template_T 
*src_attributes) ; 


or 

void _CPYNV (_NUM_Descr_T revr_descr, 
_SPCPTR receiver, 
_NUM_Descr_T src_descr, 
const _SPCPTR source); 
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Table 1 (Page 7 of 18). Machine Interface Instructions 


Instruction 


C Function Prototype 


Description 


DCPDATA #include <QSYSINC/MIH/DCPDATA> Decompresses user data 
: of a specified length. 
Function 
int dcpdata (_SPCPTR result, 
int result_length, 
_SPCPTRCN source); 
Builtin 
void _DCPDATA (_DCPD_Template_T *dcpd_t); 
DECD #include <QSYSINC/MIH/MIDTTM> The date specified by 
F . source_date is decre- 
unction mented by the date dura- 
void decd (_SPCPTR result_date, tion specified by duration. 
_SPCPTRCN source_date, The resulting date is 
_SPCPTRCN duration, placed in result_date. 
_INST_Template_T3 *inst_t); 
Builtin 
void _DECD (_SPCPTR result_date, 
_SPCPTRCN source_date, 
_SPCPTRCN duration, 
_INST_Template_T3 *inst_t); 
DECT #include <QSYSINC/MIH/MIDTTM> The time specified by 
F : source_time is decre- 
unction mented by the time dura- 
void dect (_SPCPTR result_time, tion specified by duration. 
_SPCPTRCN source_time, The resulting time is 
_SPCPTRCN duration, placed in result_time. 
_INST_Template_T3 *inst_t) 
Builtin 
void _DECT (_SPCPTR result_time, 
_SPCPTRCN source_time, 
_SPCPTRCN duration, 
_SPCPTR_Template_T3 *inst_t); 
DECTS #include <QSYSINC/MIH/MIDTTM> The timestamp specified 
Functi by source_timestamp is 
uneron decremented by the date, 
void dects (_SPCPTR result_timestamp, time or timestamp duration 
_SPCPTRCN source_timestamp , specified by duration. The 
_SPCPTRCN duration, resulting timestamp is 
_INST_Template_T3 *inst_t); placed in 
Builtin result_timestamp. 
void _DECTS (_SPCPTR result_timestamp, 
_SPCPTRCN source_timestamp, 
_SPCPTRCN duration, 
_INST_Template_T3 *inst_t); 
DESMTX #include <QSYSINC/MIH/DESMTX> Destroys a mutex. 
Builtin 
void _DESMTX (_Mutex_T « 
_Mutex_Destroy_Opt_T *); 
DEQ #include <QSYSINC/MIH/DEQ> Retrieves a queue 


Function 
void deq (_DEQ Msg Prefix_T «msg prefix, 
_SPCPTR message, 
_SYSPTR queue) ; 


Builtin 
void _DEQWAIT (_DEQ Msg Prefix_T 
«msg _prefix, 


_SPCPTR message, 
_SYSPTR *queue) ; 


message based on the 
queue type specified 
during the queue's cre- 
ation. Process is placed in 
a wait state. 
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Instruction 


C Function Prototype 


Description 


Function 


void edit (_SPCPTR receiver, 
unsigned int rcvr_length, 
_SPCPTRCN source, 
_NUM_Descr_T src_descr, 
_SPCPTR mask, 
unsigned int mask_length); 


Builtin 
void _LBEDIT (_SPCPTR receiver, 
unsigned int *rcvr_length, 
_SPCPTRCN source, 
_DPA_Template_T *src_descr, 


_SPCPTR mask, 
unsigned int *mask_length); 


DEQI #include <QSYSINC/MIH/DEQI> Retrieves a queue 
F . message based on queue 
unction type (FIFO, LIFO, or 
int deqi (_DEQ Msg Prefix_T *msg prefix, keyed). Process is not 
_SPCPTR message, placed in a wait state. 
_SYSPTR queue); 
Builtin 
int DEQ (_DEQ Msg Prefix_T *msg prefix, 
_SPCPTR message, 
_SYSPTR *queue) ; 
Return Value 
Value Meaning 
1 Message Dequeued 
0 Message Not Dequeued 
EDIT #include <QSYSINC/MIH/EDIT> The value of source is 


transformed under control 
of mask and the result is 
placed in receiver. 


EDIT with Packed 
Decimal Source 


#include <QSYSINC/MIH/EDIT> 


Function 
void edit_packed (_SPCPTR receiver, 


unsigned int rec_length, 


SPCPTRCN source, 


unsigned int src_length, 


_SPCPTR mask, 


unsigned int mask_length); 


Builtin 
void _EDITPD (_SPCPTR receiver, 
unsigned int rcvr_length, 
_SPCPTRCN source, 
unsigned int src_length, 
_SPCPTR mask, 
unsigned int mask_length); 


The value of the packed 
decimal source is trans- 
formed under control of 
mask, and the result is 
placed in receiver. 


Function 

void ensobj (_SYSPTR object); 
Builtin 

void _ENSOBJ (_SYSPTR *object); 


ENQ #include <QSYSINC/MIH/ENQ> A message is enqueued 
Functi according to the queue 
unevon type attribute specified 
void enq (_SYSPTR queue, during the queue's cre- 
_ENQ Msg _Prefix_T *msg_prefix, ation. 
_SPCPTR message); 
Builtin 
void _ENQ (_SYSPTR *system_ptr, 
_ENQ_Msg_ Prefix_T *msg_prefix, 
_SPCPTR message) ; 
ENSOBJ #include <QSYSINC/MIH/ENSOBJ> The object specified is pro- 


tected from volatile storage 
loss. 
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Instruction 


C Function Prototype 


Description 


EXTREXP #include <QSYSINC/MIH/EXTREXP> Extracts the exponent 
: portion of the floating point 
Function scalar and returns the 
int extrexp (double source); value as a 4-byte integer. 
FNDINXEN #include <QSYSINC/MIH/FNDINXEN> Searches index_obj 
: according to the search 
Function criteria specified in 
_SPCPTR fndinxen (_SPCPTR receiver, option_list and search 
_SYSPTR index_obj, argument search_arg. 
_IIX_Opt_List_T 
xoption_list, 
_SPCPTR search_arg) ; 
Builtin 
void _FNDINXEN (_SPCPTR receiver, 
_SYSPTR *index_obj, 
_IIX_Opt_List_T 
xoption_list, 
_SPCPTR search_arg); 
FNDRINVN #include <QSYSINC/MIH/FNDRINVN> Searches a specified 
' range of invocations until 
Function an invocation is found 
int fndrinvn (_INV_Template_T *inv_t, which satisfies the search 
int srch_option, criteria. 
_SPCPTRCN srch_arg, 
char compare) ; 
Builtin 
void _FNDRINVN1 (int *rel_inv_number, 
_FNDR_Search_Template_T 
*srch_t); 
or 
void _FNDRINVN2 (int *rel_inv_number, 
_INV_Template_T *inv_t, 
_FNDR_Search_Template_T 
*srch_t); 
INCD #include <QSYSINC/MIH/MIDTTM> The date specified by 
. source_date is incre- 
Function mented by the date dura- 
void incd (_SPCPTR result_date, tion specified by duration. 
_SPCPTRCN source_date, The resulting date is 
_SPCPTRCN duration, placed in result_date. 
_INST_Template_T3 *inst_t); 
Builtin 
void _INCD (_SPCPTR result_date, 
_SPCPTR source_date, 
_SPCPTR duration, 
_INST_Template_T3 *inst_t); 
INCT #include <QSYSINC/MIH/MIDTTM> The time specified by 


Function 


void inct (_SPCPTR result_time, 
_SPCPTRCN source_time, 
_SPCPTRCN duration, 
_INST_Template_T3 *inst_t); 


Builtin 


void _INCT (_SPCPTR result_time, 
_SPCPTRCN source_time, 
_SPCPTRCN duration, 
_INST_Template_T3 *inst_t); 


source_time is incre- 
mented by the time dura- 
tion specified by duration. 
The resulting time is 
placed in result_time. 
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INCTS #include <QSYSINC/MIH/MIDTTM> The timestamp specified 
J by source_timestamp is 
Function incremented by the date, 
void incts (_SPCPTR result_timestamp, time or timestamp duration 
_SPCPTREN source_timestamp , specified by duration. The 
_SPCPTRCN duration, resulting timestamp is 
_INST_Template_T3 *inst_t); placed in 
Builtin result_timestamp. 
void _INCTS (_SPCPTR result_timestamp, 
_SPCPTRCN source_timestamp, 
_SPCPTRCN duration, 
_INST_Template_T3 *inst_t); 
INSINXEN #include <QSYSINC/MIH/INSINXEN> Inserts one or more new 
: entries into the index_obj 
Function according to the criteria 
void insinxen (_SYSPTR index_obj, specified on option_list. 
_SPCPTR new_entry, 
_IIX_Opt_List_T 
xoption_list); 
Builtin 
void _INSINXEN (_SYSPTR *index_obj, 
_SPCPTR new_entry, 
_IIX_Opt_List_T 
xoption_list); 
LOCK #include <QSYSINC/MIH/LOCK> Requests the lock(s) for 
F 4 the system object(s) identi- 
uneton fied be allocated to the 
issuing process. 
void lock (_SYSPTR object, 
MI_Time wait_time, 
char lock_state); 
Builtin 
void Lock (_LOCK_Template_T *lock_request); 
or 
void _LOCK (_LOCK_Template_T *lock_request); 
LOCKMTX #include <QSYSINC/MIH/LOCKMTX> Locks a mutex. 
Builtin 
void _LOCKMTX (_Mutex_T *, 
_Mutex_Lock_T *); 
LOCKSL #include <QSYSINC/MIH/LOCKSL> Grants the space 
F ‘ location(s) to the issuing 
unction process according to the 
void locks] (_SPCPTR location, lock request. 
char lock_state); 
void locks12 (_SPCPTR location, 
_MI_Time wait_time, 
char lock_state); 
Builtin 
void _LOCKSL1 (_SPCPTR *location, 
char* lock _state); 
void _LOCKSL2 (_LOCKSL_Template T * 
*lock_t); 
MATACTAT #include <QSYSINC/MIH/MATACTAT> Materializes the informa- 
Functi tion selected by 
ee attr_selection for the 
void matactat (_MTACT_Template_T *receiver, program activation speci- 
unsigned int act_mark, fied by act_mark and 
char attr_selection); stores it in receiver. 
Builtin 
void _MATACTAT (_MTACT_Template_T *receiver, 
unsigned int *act_mark, 
char *attr_selection); 
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Description 


MATAGAT #include <QSYSINC/MIH/MATAGAT> Materializes the attributes 
: of access_group into 
Function receiver. 
void matagat (_MAGAT_Template_T *receiver, 
_SYSPTR access_group) ; 
Builtin 
void _MATAGAT (_MAGAT_Template_T *receiver, 
_SYSPTR *access_group) ; 
MATAGPAT #include <QSYSINC/MIH/MATAGPAT> Materializes the informa- 
F , tion selected by 
unction attr_selection for activation 
void matagpat (_MAGP_Template_T *receiver, group act_grp_mark and 
unsigned int act_grp_mark, stores it in receiver. 
char attr_selection); 
Builtin 
void _MATAGPAT (_MAGP_Template_T *receiver, 
unsigned int *act_grp_mark, 
char *attr_selection); 
MATAOL #include <QSYSINC/MIH/MATAOL> Materializes the current 
Functi allocated locks on a 
uneton system object or space 
void mataol (_MAOL_Template_T *receiver, location into receiver. 
_ANYPTR pointer); 
Builtin 
void _MATAOL (_MAOL_Template_T «receiver, 
_ANYPTR *pointer); 
MATINVAT #include <QSYSINC/MIH/MATINVAT> Materializes the attributes 
F ‘ of the specified invocation 
unction into receiver. 
void matinvat (_SPCPTR receiver, 
_INV_Template_T *inv_t, 
int attr_id, 
int rcevr_length); 
Builtin 
void _MATINVAT1 (_SPCPTR receiver, 
_Select_Template_T 
*select_t); 
or 
void _MATINVAT2 (_SPCPTR receiver, 
_INV_Template_T *inv_t, 
_Select_Template_T 
*select_t); 
MATINXAT #include <QSYSINC/MIH/MATINXAT> Materializes the creation 
F ; attribute and current oper- 
unction ational statistics of 
void matinxat (_IIX_Template_T «receiver, index_obj into receiver. 
_SYSPTR index_obj); 
Builtin 
void _MATINXAT (_IIX_Template_T *receiver, 
_SYSPTR *index_obj); 
MATMATR #include <QSYSINC/MIH/MATMATR> Materializes the machines 


Function 
void matmatr (_MMTR_Template_T *receiver, 
short attr); 
Builtin 
void _MATMATR1 (_MMTR_Template_T *receiver, 
short xattr); 


attributes specified by attr 
into receiver. 
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C Function Prototype 


Description 


MATMDATA #include <QSYSINC/MIH/MATMDATA> Materializes the requested 
; machine data into receiver. 
Function 
void matmdata (_MDATA_Template_T *receiver, 
short options); 
Builtin 
void _MATMDATA (_MDATA Template *receiver, 
short options); 
MATMTX #include <QSYSINC/MIH/MATMTX> Materializes a mutex. 
Builtin 
void _MATMTX (_Mutex_Mat_T *, 
_Mutex_T *, 
_Mutex_Mat_Opt_T *); 
MATOBJLK #include <QSYSINC/MIH/MATOBJLK> The current lock status of 
F ‘i the object or space 
unction location is materialized into 
void matobjlk (_MOBJL_Template_T *receiver, receiver. 
_ANYPTR object) ; 
Builtin 
void _MATOBJLK (_MOBJL_Template_T *receiver, 
_ANYPTR *object); 
MATPG #include <QSYSINC/MIH/MATPG> program is materialized 
‘ into receiver. 
Function 
void matpg (_MATPG_Template_T *receiver, 
_SYSPTR program) ; 
Builtin 
void _MATPG (_MATPG_Template_T *receiver, 
_SYSPTR *program) ; 
MATPRMTX #include <QSYSINC/MIH/MATPRMTX> Materializes process mutex 
ae locks. 
Builtin 
void _MATPRMTX (_Mutex_Matpr_T *, 
_SYSPTR *, 
_Mutex_Matpr_Opt_T *); 
MATPTR #include <QSYSINC/MIH/MATPTR> The materialized form of 


Function 


void matptr (_MPTR_Template_T *receiver, 
_ANYPTR pointer); 


Builtin 


void _MATPTR (_MPTR_Template_T *receiver, 
_ANYPTR *pointer); 


pointer is returned in 
receiver 


MATPTRL #include <QSYSINC/MIH/MATPTRL> Finds the pointers in a 
Funell subset of a space and 
gnevon produces a bit mapping of 
void matptr] (_MPTL_Template_T «receiver, their relative locations. 
_SPCPTRCN source, 
int length); 
Builtin 
void _MATPTRL (_MPTL_Template_T *receiver, 
_SPCPTRCN source, 
int *length); 
MATPRAGP #include <QSYSINC/MIH/MATPRAGP> A list of the activation 


Function 

void matpragp (_MPRAG_Template_T *receiver); 
Builtin 

void _MATPRAGP (_MPRAG_Template_T *receiver); 


groups which exist in the 
current process are 
returned in receiver. 
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Instruction 


C Function Prototype 


Description 


MATPRATR #include <QSYSINC/MIH/MATPRATR> Materialize attributes of 
F , control_spc into receiver 
unction according to the specified 
void matpratr (_MPRT_Template_T *receiver, options. 
_SYSPTR control_spc, 
char options); 
Builtin 
void _MATPRATR1 (_MPRT_Template_T *receiver, 
char *options); 
or 
void _MATPRATR2 (_MPRT_Template_T *receiver, 
_SYSPTR *control_spc, 
char *options); 
MATPRLK #include <QSYSINC/MIH/MATPRLK> The lock status of the 
F - process identified by pcs is 
unction materialized into receiver. 
void matpr1k (_MPRL_Template_T «receiver, 
_SYSPTR pcs); 
Builtin 
void _MATPRLK1 (_MPRL_Template_T *receiver); 
or 
void _MATPRLK2 (_MPRL_Template_T *receiver, 
_SYSPTR *pcs); 
MATQAT #include <QSYSINC/MIH/MATQAT> The attributes of the queue 
F : are materialized into 
unction receiver 
void matqat (_MQAT_Template_T *receiver, 
_SYSPTR queue); 
Builtin 
void _MATQAT (_MQAT Template_T *receiver, 
_SYSPTR *queue) ; 
MATQMSG #include <QSYSINC/MIH/MATQMSG> Materializes selected mes- 
F : sages in queue into 
unction receiver. 
void matqmsg (_MQMS_Template_T *receiver, 
_SYSPTR queue, 
char selection, 
int max_key, 
int max_msg, 
_SPCPTR key); 
Builtin 
void _MATQMSG (_MQMS_Template_T *receiver, 
_SYSPTR *queue, 
_MQMS_Select_T *selection); 
MATRMD #include <QSYSINC/MIH/MATRMD=> The data items requested 
F 7 by control are materialized 
unction into receiver 
void matrmd (_MATRMD_Template_T *receiver, 
_SPCPTR control); 
Builtin 
void _MATRMD (_MATRMD_Template_T *receiver, 
_SPCPTR control); 
MATS #include <QSYSINC/MIH/MATS> The current attributes of 


Function 


void mats (_SPC_Template_T *receiver, 
_SYSPTR space_object); 


Builtin 


void MATS (_SPC_Template_T *receiver, 
_SYSPTR *space_object); 


the space object specified 


by space_object are mai 
rialized into receiver. 


te- 
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Instruction 


C Function Prototype 


Description 


MATSELLK #include <QSYSINC/MIH/MATSELLK> Materializes the locks held 
F , by the process issuing this 
unction instruction for the object or 
void matsellk (_MSLL_Template_T *receiver, space location specified. 
_ANYPTR pointer); 
Builtin 
void _MATSELLK (_MSLL_Template_T *receiver, 
_ANYPTR *pointer); 
MATSOBJ #include <QSYSINC/MIH/MATSOBuJ> Materializes the identity 


Function 


void matsobj (_MSOB_Template_T «receiver, 
_SYSPTR object) ; 


Builtin 


void _MATSOBJ (_MSOB_Template_T *receiver, 
_SYSPTR *object); 


and size of a system 
object addressed by object 
into receiver. 


MATTOD #include <QSYSINC/MIH/MATTOD> Materializes the 
fi time _of_day clock. 
Function 
void mattod (_MI_Time time_of day); 
Builtin 
void MATTOD (_MI_Time time_of day); 
MITIME #include <QSYSINC/MIH/MICOMMON> Sets receiver to the 
F ‘ AS/400 system value for 
unction time. 
_MI_TIME *mitime (_MI_Time *receiver, int hours, int minutes, 
int seconds, int hundredths); 
MODASA #include <QSYSINC/MIH/MODASA> Extend the current allo- 
F “ cation of automatic storage 
unction by size bytes. 
_SPCPTR modasa (unsigned int size); 
Builtin 
_SPCPTR _MODASA (unsigned int size); 
MODINX #include <QSYSINC/MIH/MODINX> Modifies the selected attri- 
7 butes of index_obj. 
Function 
void modinx (_SYSPTR index_obj, 
char mod_option); 
Builtin 
void _MODINX (_SYSPTR *index_obj, 
unsigned int *mod_option); 
MODS #include <QSYSINC/MIH/MODS> Resize the space associ- 
Functi ated with space_object to 
unction size bytes. 
void mods (_SYSPTR space_object, 
int size); 
Builtin 
void _MODS1 (_SYSPTR *space_object, 
int *size); 
MODS2 #include <QSYSINC/MIH/MODS2> The attributes of the space 


Function 
void mods2 (_SYSPTR space_object, 
_SPC_MOD_T *space_t); 
Builtin 


void MODS2 (_SYSPTR *space_object, 
_SPC_MOD_T *space_t); 


associated with 
space_object are modified 
with the attribute values 
specified in space_t. 
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Instruction 


C Function Prototype 


Description 


RSLVSP #include <QSYSINC/MIH/RSLVSP> Locates an object identi- 
fied by the object identifier 
Function (type, name, and library) 
_SYSPTR rslvsp (_OBJ_TYPE_T obj_type, and returns the object's 
_OBJ_NAME obj_name, addressability in a system 
_LIB_NAME lib_name, pointer. 
_REQ_AUTH auth) ; 
Builtin 
void _RSLVSP1 (_SYSPTR *ptr_to_object); 
or 
void _RSLVSP2 (_SYSPTR *ptr_to_object, 
_RSLV_Template_T 
*objid_and_authreq); 
or 
void _RSLVSP3 (_SYSPTR *ptr_to object, 
_SYSPTR *library); 
or 
void _RSLVSP4 (_SYSPTR *ptr_to object, 
_RSLV_Template_T 
*xobjid_and_authreq, 
_SYSPTR *library) ; 
or 
void _RSLVSP5 (_SYSPTR *ptr_to_object, 
_REQ_AUTH *auth) ; 
or 
void _RSLVSP6 (_SYSPTR *ptr_to object, 
_RSLV_Template_T 
*xobjid_and_authreq, 
_REQ_AUTH *auth) ; 
or 
void _RSLVSP7 (_SYSPTR *ptr_to_object, 
_SYSPTR *library, 
_REQ_AUTH *auth) ; 
or 
void _RSLVSP8 (_SYSPTR *ptr_to object, 
_RSLV_Template_T 
*objid_and_authreq, 
_SYSPTR *library, 
_REQ_AUTH *auth) ; 
RETCA #include <QSYSINC/MIH/RETCA> Retrieves from the 
: machine and returns the 
Function 4-byte value containing the 
unsigned int retca (unsigned int mask); selected computational 
attributes. 

RMVINXEN #include <QSYSINC/MIH/RMVINXEN> The index entries identified 
. by option_list and 
Function search_arg are removed 
_SPCPTR rmvinxen (_SPCPTR receiver, from index_obj and 

_SYSPTR index_obj, returned in receiver. 
_IIX_Opt_List_T 
xoption_list, 
_SPCPTR search_arg); 
Builtin 
void _RMVINXEN1 (_SYSPTR *index_obj, 
_IIX_Opt_List_T 
xoption_list, 
_SPCPTR search_arg) ; 
or 
void _RMVINXEN2 (_SPCPTR receiver, 
_SYSPTR *index_obj, 
_IIX_Opt_List_T 
xoption_list, 
_SPCPTR search_arg) ; 
SCANWC #include <QSYSINC/MIH/SCANWC> The source string is 


Function 


int scanwc (char *source, 
_SCWC_Control_T *controls, 
char options); 


scanned for occurrences of 
a character value satis- 
fying the criteria in control 
and options. 
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SCANX #include <QSYSINC/MIH/SCANX> The source string is 
Builti scanned for occurrences of 
uiltin a character value satis- 
int _SCANX(char **source, fying the criteria in control! 
_SCWC_Control_T *controls, and options. 
int options); 
SETACST #include <QSYSINC/MIH/SETACST> Specifies the access state 
F . that the issuing process 
unction has for a set of objects or 
subobject elements in the 
void setacst (_ANYPTR object, execution interval following 
char state_code, the execution of this 
int pool_id, instruction. 
int space_length); 
Builtin 
void Setacst (_SETACST_Template_T 
xaccess_t); 
or 
void _SETACST (_SETACST_Template_T 
*xaccess_t); 
SETBTS #include <QSYSINC/MIH/SETBTS> Set the bit in bit_string cor- 
, responding to bit_offset. 
Function 
void setbts (_SPCPTR bit_string, 
unsigned int bit_offset); 
Builtin 
void _SETBTS (_SPCPTR bit_string, 
unsigned int bit_offset); 
SETCA #include <QSYSINC/MIH/SETCA> Sets the computation attri- 
F . butes selected and stores 
unction them into the machine. 
void setca (unsigned int new_value, 
unsigned int mask); 
SETSPFP #include <QSYSINC/MIH/SETSPFP> Returns a system pointer 
F : to the system object 
unction addressed by pointer. 
_SYSPTR setspfp (_ANYPTR pointer) ; 
Builtin 
_SYSPTR _SETSPFP (_ANYPTR pointer); 
SETSPPFP #include <QSYSINC/MIH/SETSPPFP> Returns addressability to a 
Function space object from pointer. 
_SPCPTR setsppfp (_ANYPTR pointer); 
Builtin 
_SPCPTR _SETSPPFP (_ANYPTR pointer); 
SETSPPO #include <QSYSINC/MIH/SETSPPO> The value of the offset is 
Functi assigned to the offset 
uneven portion of pointer. 
_SPCPTR setsppo (_SPCPTR pointer, 
int offset); 
STSPPO #include <QSYSINC/MIH/STSPPO> Returns the offset value of 
i pointer. 
Function 
int stsppo (_SPCPTR pointer); 
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TESTAU #include <QSYSINC/MIH/TESTAU> Verifies that the object 
F : authorities and/or owner- 
unction ship rights specified by 
short testau (_SYSPTR obj, req_auth are currently 
short offset, available to the process. 
short req_auth); 
Builtin 
int _TESTAU1 (_ANYPTR *pointer, 
short *req_auth) ; 
or 
int _TESTAU2 (short *avail_auth, 
_ANYPTR *pointer, 
short *req_auth) ; 
Return Value 
Value Meaning 
1 Authorized 
0 Not Authorized 
TRIML #include <QSYSINC/MIH/TRIML> Returns the length of string 
F 7 after trim_char has been 
unction trimmed from the end. 
int trim] (char *string, 
char trim_char); 
TSTBTS #include <QSYSINC/MIH/TSTBTS> Test the bit in bit_string 
, corresponding to bit_offset. 
Function 
int tstbts (_SPCPTR bit_string, 
unsigned int bit_offset); 
Builtin 
int _TSTBTS (_SPCPTR bit_string, 
unsigned int bit_offset); 
UNLOCK #include <QSYSINC/MIH/UNLOCK> Releases the object lock(s) 
i specified. 
Function 
void unlock (_SYSPTR object, 
char unlock_option, 
char lock_state); 
Builtin 
void Unlock (_LOCK_Template_T 
xunlock_request) ; 
or 
void UNLOCK (_LOCK_Template_T 
xunlock_request) ; 
UNLOCKSL #include <QSYSINC/MIH/UNLOCKSL> Releases the lock(s) for 
F : the specified space 
unction location(s) 
void unlocks] (_SPCPTR spc_loc, 
char lock_state); 
Builtin 
void _UNLOCKSL1 (_SPCPTR *spc_loc, 
char* lock_state); 
or 
void _UNLOCKSL2 (_LOCKSL_Template_T 
*xlock_t); 
WAITTIME #include <QSYSINC/MIH/WAITTIME> Causes the process to wait 


Function 


void waittime (_MI_Time *wait_interval, 
short options); 


Builtin 


void WAITTIME (WAIT Template T *wait_t); 
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XFRLOCK #include <QSYSINC/MIH/XFRLOCK> The receiving process is 
F 7 allocated the locks desig- 
unction nated in xfer_t. 
void xfrlock (_SYSPTR process, 
_SYSPTR object, 
char lock_state_to_transfer) ; 
Builtin 
void _XFRLOCK (_SYSPTR *receiver, 
_LOCK_Template_T *xfer_t); 
XLATEWT #include <QSYSINC/MIH/XLATEWT> Translates the source 


Function 


void xlatewt (char *receiver, 
const char «source, 
const char *table); 


Builtin 


void _XLATEB (_SPCPTR source, 
_SPCPTRCN table, 
unsigned int length); 


characters under control of 
the translate table. 
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Index 
enq 104 
A ensobj 106 
atiexit 15 extrexp 108 
C F 
cdd 17 fndinxen 110 
clrbts 21 fndrinvn 113 
cmppspad 23 
cmpptra 25 
cmpptrt 28 I 
cprdata 31 incd 116 
cpybla 69 inct 120 
cpyblap 71 incts 123 
cpyhexnn 73 insinxen 127 
cpyhexnz 75 
cpyhexzn 77 L 
cpyhexzz 79 
cpynv 81 lock 130 
ctd 33 locks! 133 
ctsd 36 lockslI2 136 
cvtbc 40 
cvtcb 42 M 
cvich 44 Machine Interface Support Include File 155 
cvitcm 46 matactat 139 
cvics 48 matagat 141 
cvid 50 matagpat 145 
cvtefn 54 mataol 148 
cvthc 56 matinvat 150 
cvtmc 58 matinxat 153 
cvisc 60 matmatr 155 
evit 62 matmdata 157 
cvtts 65 matobjlk 159 
matpg 161 
D matpragp 168 
depdata 83 matpratr 171 
decd 85 matprik 173 
deck 89 matptr 163 
dacts 92 matptrl 165 
deq 96 matgat 176 
deai 98 matqmsg 178 
matrmd 182 
mats 184 
E matsellk 186 
edit 100 matsobj 188 
edit packed decimal 102 mattod 190 
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Index 


mitime 192 
modasa 195 
modinx 197 
mods 200 
mods2 203 


R 

retca 208 
rmvinxen 211 
rslvsp 206 


S 


scanwce 214 
setacst 216 
setbts 219 
setca 221 
setspfp 225 
setsppfp 228 
setsppo 231 
stsppo 233 


T 


testau 234 
triml 236 
tstbts 238 


U 


unlock 240 
unlocksl 243 


W 


waittime 246 


X 
xfrlock 248 
xlatewt 252 


276 = Mi Library Reference 


